Управление документацией в растущей компании: DocFX + Gitea + «Этос»
По мере увеличения кодовой базы любая компания начинает испытывать потребность в упорядочивании разрозненной документации, иными словами — создании собственной «базы знаний». Как следует из самого термина, речь идет о структурированном хранилище информации, причем способов её организовать существует великое множество. И вот здесь стоит задуматься, а кому и зачем, собственно, нужна база знаний, ведь от ответов на эти вопросы будет зависеть не только выбор конкретной технологии, но и сама архитектура будущего сервиса.
Кому и зачем это нужно
Начнем с вопроса «кому». Очевидно, что рядовому пользователю системы, ее администратору и разработчику нужна разная информация. Более того, существуют технические нюансы, о которым обычным пользователям знать вообще не следует, например, данные о серверной инфраструктуре заказчиков. Соответственно, нужно либо разграничивать доступ к разделам базы знаний, либо и вовсе делать несколько изолированных хранилищ.
Определившись с целевой аудиторией базы знаний, можно переходить к постановке задач. В нашем случае они выглядели так:
Сократить время на поиск нужной информации опытными разработчиками.
Оптимизировать обучение новых разработчиков, то есть, с одной стороны, уменьшить время на овладение нужными знаниями, а с другой, «разгрузить» опытных коллег, до сих пор тративших много времени на объяснение «базы» каждому новичку.
Освободить техподдержку от решения типовых задач по установке и настройке ПО, описав соответствующие процессы.
Максимально автоматизировать документирование нового кода.
Обеспечить техписателям мгновенный доступ ко всем версиям всех документов по каждому из контрактов компании.
Плюс к этому требовалось соблюсти еще несколько условий:
чтобы исключить риски от использования стороннего проприетарного ПО, все применяемые инструменты должны быть либо оупенсорсными, либо собственными;
описание методов должно автоматически генерироваться из кода;
вся документация должна быть легко актуализируема.
Сначала был код
Исходя из вышесказанного, у нас получилась следующая структура базы знаний:
Роль основного хаба для всех сотрудников играет хранилище репозиториев, развернутое на собственных серверах с помощью веб-приложения Gitea. Каждый из репозиториев наряду с кодом включает в себя набор вики-страниц, содержащих внутреннюю документацию разработчиков: стандарты написания кода, настройки серверов, инструкции по сборке и развертыванию проектов и пр. — словом, информацию, не рассчитанную на широкую аудиторию.
Другим источников внутренней документации является сам код, а точнее добавляемые техписателями в исходные файлы комментарии с описанием методов. Такие описания стандартизированы и оформляются с помощью набора XML-тегов по следующему плану:
функция метода;
описание параметров;
возвращаемое значение;
примеры использования.
Делается это не только для обеспечения единообразия документации, но и для того, чтобы при сборке проекта в Visual Studio компилятор C# «упаковал» нужные комментарии в отдельные XML-файлы (в настройках MSBuild для свойства GenerateDocumentationFile должно быть задано значение true). И уже из этих файлов также автоматически будут сгенерированы веб-страницы.
DocFX: сценарии использования
За преобразование XML в HTML отвечает DocFX — генератор статических сайтов с открытым кодом. Для работы приложению нужен установленный .NET SDK 6.0, оно запускается в том числе под Linux и не требует сложной настройки. В нашем случае кастомизация заключалась в создании собственного шаблона (template) отображения веб-страниц. Для этого мы добавили в проект папку с CSS-файлами, расширением для библиотеки Lunr, позволяющим осуществлять поиск на русском языке, а также отредактировали token.json, вписав русский перевод для основных заголовков. После этого осталось лишь указать нужные пути в docfx.json — и генератор был готов к работе.
Его функциональность, однако, не сводится к «вытаскиванию» комментариев из текста. DocFX в умелых руках — это удобный инструмент для создания многостраничных сайтов с документацией, поддерживающих сложную структуру разделов и подразделов, разнообразные элементы навигации, но главное — легко масштабируемых и актуализируемых.
Поскольку тексты для DocFX пишутся в разметке Markdown, а их структура задается в специальных файлах-оглавлениях в формате YAML, с документацией удобно работать как с кодом (Docs as Code). На практике это означает, что техписатель вносит правки в свой раздел, после чего «коммитит» изменения в специально созданный гит-репозиторий, где они становятся доступны всем его коллегам. Когда изменения накапливаются, актуальная версия проекта «скармливается» DocFX, а на выходе мы получаем готовый многостраничник, который остается только выгрузить на хостинг.
Понятно, что в этом случае речь уже идет о документации, ориентированной на широкую аудиторию. Наряду с описанием методов на сайте публикуется и регулярно обновляется руководство по установке и настройке системы, сценарии работы с отдельными ее модулями, описание всех таблиц базы данных и связей между ними, то есть всё то, что может понадобится пользователю и администратору.
От архива — к ERP-системе
Итак, теперь в нашей базе знаний есть документация для внешних пользователей и для разработчиков — остается определиться, как будем хранить документацию, которую пишем для заказчиков.
В принципе, для этого можно было бы создать отдельный репозиторий, но мы решили поступить иначе. Во-первых, практически все документы заказчики получают от нас в формате MS Word, работать с которым в Git не очень удобно. Во-вторых, не все наши техписатели работают с «Гитом», зато все работают с «Этосом» — нашим основным продуктом, представляющим собой платформу для создания ERP-систем.
На ее основе за пару часов разработчики собрали конфигурацию, позволившую, во-первых, систематизировать весь наш архив, разложив все документы по нужным папкам, а во-вторых, вести версионность добавляемых файлов. Теперь мы не только знаем, кто и когда добавил новую версию того или иного проектного решения или инструкции, но можем прямо в системе сравнить тексты двух версий, чтобы увидеть изменения.
Итак, мы бегло рассмотрели все ключевые элементы нашей базы знаний. Несмотря на то что описанный вид она приняла сравнительно недавно, мы уже имели возможность оценить ее преимущества. Самое очевидное из них — это ускорение «онбординга» новых сотрудников, которые включились в решение боевых задач уже на второй-третьей неделе работы (раньше на это уходил минимум месяц). Более того, некоторые из них даже умудрились отметиться на страницах корпоративной «Вики». Эффект от «автокомментария» исходного кода оценить сложнее, но сомнений в необходимости этого предприятия нет, тем более что требование наличия в документации детального описания всех классов и методов в отдельных случаях прямо прописывается в ТЗ.
В заключение еще раз подчеркнем, что описанная система — это лишь один из многих вариантов реализации базы знаний. Только с XML-комментариями в коде наряду с DocFX умеют работать еще как минимум Sandcastle и Doxygen, а средств структурированного хранения документации с поддержкой версионности и вовсе существует великое множество.
Также очевидно и то, что рассмотренная конфигурация пока далека от завершения. Из ближайших планов — превратить хранилище проектной документации в полноценную систему управления технической информацией со своей ролевой моделью, формализованными бизнес-процессами, инструментами статистики и аналитики и т.п., но это будет уже совсем другая история.
Habrahabr.ru прочитано 2612 раз
