В IT компаниях системные аналитики, бизнес-аналитики, аналитики данных и другие специалисты, работающие в области анализа, ежедневно обрабатывают большое количество информации, формируя документацию. К документации относятся:
- Проектная документация: технический проект (ТП) или упрощенный технический проект (УТП). Эти документы описывают конечное представление о реализации продукта с учетом предъявленных требований на каждой стадии проектирования;
- Сервисная документация: инструкции пользователя, паспорт проекта, паспорт интеграций, инструкция администратора проекта и так далее. Данный вид документации описывает как необходимо пользоваться с разработанной информационной системой, из чего она состоит, что можно сделать пользователь с помощью инструмента;
- Постановки команде разработки: описание функционала, который необходимо реализовать разработчикам. Может быть представлено в виде багов (bugs) или UserStory (US, пользовательская история).
Эта документация может быть реализована в различных формах представления:
- текстовые документы, созданные с помощью, например, Microsoft Word, LibreOffice Writer, Google Docs и других текстовых редакторов;
- табличные данные, реализованных в программных средствах, таких как, например, Google Sheets, Microsoft Excel, LibreOffice Calc и других инструментах;
- веб-страницы документов в wiki-системах, таких, как, например, Confluence, MediaWiki, DokuWiki и других системах;
- задачи в программных инструментах управления проектами, например, Jira, Azure DevOps, VersionOne и других программных средствах;
- текстовые файлы на языке разметки: Markdown, reStructuredText, Asciidoc и других.
Все эти формы ведения документации активно используются аналитиками в качестве средства сохранения данных, а остальными членами команды разработки – в качестве источника информации по уже разработанному функционалу или задачам, которые только предстоит разработать.
Однако, как видно из приведенного списка различных форм документации, этих видов множество, что может повлечь за собой ряд проблем. В данной статье будут рассмотрены потенциальные проблемы ведения документации в различных формах.
Тем не менее из описанного перечня возможных форм представления документации, один из пунктов является наиболее удобным и современным – это ведение документации с помощью языков разметки. В данной статье также будут рассмотрены преимущества использования данного ведения информации.
Подход, используемый для создания документации на языках разметки, как код, называется Doc as Code (документация, как код). Этот подход подразумевает создание документации, как и создание кодовой базы проекта, в репозитории – с помощью IDE, с системой контроля версий и анализом добавляемых файлов в репозиторий: автоматические проверки CI/CD и утверждение со стороны коллег.
Автоматическая проверка CI/CD позволит в момент оформления pull-request с помощью системы контроля версий git проверить:
- собирается ли приложение с документацией;
- проходят ли тесты, если они есть;
- присутствуют ли конфликты в слиянии кода и, если они присутствуют, предупредить об этом, чтобы разработчик устранил конфликты.
Под утверждением со стороны коллег подразумевается:
- проверка аналитического pull-request со стороны других аналитиков на наличие необходимых артефактов;
- проверка аналитического pull-request с постановкой со стороны разработчиков, чтобы указать на разделы, которые непонятны для реализации;
- проверка на орфографию, пунктуацию;
- проверка на синтаксис языка разметки;
- полноту и достаточность информации в новом документе или постановке.
Doc as Code подразумевает использование определенных инструментов для создания документации, как код. К таким инструментам относятся:
- IDE для создания файлов в репозиторий, например, Visual Studio Code;
- Системы управления версиями, например, git;
- Языки разметки, например, Markdown и Asciidoc;
- Инструменты, конвертирующие файлы на языке разметки в статические веб-сайты, например, Antora и Hugo;
- Инструменты сборки, например, Jenkins.
Данный подход на сегодняшний день применяется в лидирующих современных IT компаниях, таких как, например, Google. Однако Doc as Code используется не во всех российских компаниях. Причины отсутствия ведения документации с применением подхода Doc as Code в российских IT компаниях:
- Не все российские компании по разработке информационных систем знаю про подход Doc as Code, поскольку данный подход относительно новый: он появился в начале второго десятилетия 21-го века;
- Не все российские компании используют новейшее ПО для разработки систем, поэтому у них нет возможности внедрить Doc as Code;
- Не у всех компаний есть возможность выделять кадры, которые исследуют область внедрения нового подхода в компанию, а затем обучат сотрудников;
- Страх нового и «выход из зоны комфорта». Аналитики привыкли работать с документацией, например, в формате текстовых документов с помощью Microsoft Word, поэтому внедрение подхода Doc as Code может испугать сотрудников работать с кодом и вызвать с их стороны сопротивление;
- Юридические и нормативные требования. В некоторых случаях российские компании могут быть ограничены в применении подхода Doc as Code из-за юридических и нормативных требований.
Все препятствия, описанные выше, приводят к невозможности внедрения подхода ведения документации как код. Рассмотрим проблемы, которые возникают у команд разработки, при отсутствии ведения подхода Doc as Code:
- Отсутствие формализации ведения документации. Так как документация может вестись на проектах с помощью различных форм представления, то и создать единые требования к ведению документации невозможно.
- Отсутствие формализации ведения документации влечет за собой неудобство работы с документацией. Например, сотрудник оформлял на одном проекте документацию с помощью Microsoft Word, но затем сотрудника перевели на другой проект, где предыдущий аналитик вел документацию в wiki-системах. Для сотрудника это вызовет дискомфорт и, как следствие, возможную задержку в составлении документации из-за процесса привыкания к ведению документации по новым правилам.
- Отсутствие версионности создания документации и историчности внесения изменений.
Это влечет за собой несколько последствий:
- Трудность в отслеживании изменений. Без ведения историчности трудно определить, кто внес изменения в документацию, почему были внесены изменения и когда они были внесены;
- Потенциальная потеря изменений, которая повлечет за собой искажение информации и повреждению документации;
- Легкость внесения изменений. Если сотрудники не следят за версиями документации, то это означает, что ее можно в любой момент изменить и это может исказить корректность информации;
- Пониженная ответственность. Отсутствие версионности и историчности может снизить ответственность за внесение изменений, поскольку трудно определить, кто внес конкретное изменение.
Ведение документации в различных местах хранения информации, например, Confluence используется для хранения методик, Jira и Azure DevOps для ведения постановок (но при этом постановки используют информацию из методик на Confluence), на рабочих местах сотрудников в Microsoft Word для ведения пользовательских инструкций. Это влечет за собой несколько последствий:
- сложность поиска необходимой информации в рамках одного проекта;
- сложность поиска информации в пространстве компании;
- отсутствия единого источника «правды», в котором хранится актуальная информация по проекту;
- сложность поддержки нескольких мест хранения информации параллельно;
- сложность адаптации нового сотрудника, которому придется запрашивать доступ к различным корпоративным системам;
- Недоступность информации, если документация велась на рабочем месте сотрудника, который ушел в отпуск или на больничный. Также есть вероятность полной потери информации, если сотрудник уволился и не передал документацию коллегам.
Отсутствие проверки созданной документации, что так же влечет за собой ряд последствий:
- Документация с постановкой команде разработки может быть неполной, без артефактов, таких как, например, диаграммы взаимодействия back-front, ER-диаграммы и так далее;
- Документация с постановкой команде разработки может быть не понятно описана для программиста, что вызовет дополнительные вопросы и избыточные обсуждения задачи, потерю рабочего времени;
- Наличие орфографических и пунктуационных ошибок;
- Отсутствие в постановке задачи полного набора требований, который заявлял заказчик;
- Из предыдущего пункта вытекает проблема срыва сроков поставки функционала, поскольку, если не все требования были учтены, то их необходимо заново заносить в новую постановку, разрабатывать и тестировать отдельно, что требует дополнительного времени.
Всех описанных проблем можно избежать, внедрив в IT компании подход Doc as Code, имеющий ряд преимуществ:
- Формализация ведения документации. Для того чтобы внедрить подход Doc as Code, необходимо создать методику ведения документации и работы с ней, что позволит зафиксировать требования к генерируемой документации на проектах;
- Гибкость и ротация сотрудников. Если какой-либо сотрудник уволился, ушел в отпуск или заболел и его необходимо заменить другому сотруднику или если руководство решило ротировать сотрудника на другой проект, то человеку будет комфортно адаптироваться на другом месте, поскольку процессы настроены идентично;
- Импортозамещение. Самые популярные инструменты для ведения документации – Confluence, Jira, Azure DevOps – иностранная разработка. В современных реалиях российским компаниям, особенно если компания государственная, необходимо переходить на отечественное программное обеспечение или, как минимум, заменять санкционное;
- Версионность. Doc as Code работает через систему контроля версий, поэтому каждое изменение в документации отражается в истории изменений, что позволит отследить за эволюцией проекта;
- Невозможность потери данных. Как уже было сказано, Doc as Code работает через систему контроля версий, поэтому все изменения хранятся в истории системы контроля версий, что позволит восстановить информацию, если вдруг она была удалена;
- Ведение документации в одном месте – репозитории. Коллеги по проекту, новые сотрудники, пользователи информационной системы, руководители проекта и остальные коллеги будут обращаться к одному источнику информации. Соответственно, не будет тратиться время на поиск информации, как в рамках проекта, так и компании в целом. Также новому сотруднику будет достаточно запросить доступ только к одному ресурсу – стенду с документацией;
- Постоянный доступ к актуальной информации. Если необходимо найти какой-либо документ, то не нужно просить его отправить другого сотрудника. Также, если сотрудник, который обладал документом, заболел или в отпуске, то не нужно ждать его возвращения;
- Проверка качество документации. Так как подход Doc as Code подразумевает ведение документации с использованием системы контроля версий, то создаваемую документацию смогут проверять коллеги на этапе формирования pull-requst, что позволит не пропустить в мастер некорректный документ. С учетом проверки документации со стороны коллег, документ или постановка будут с большей вероятностью корректны, полностью описанные и без ошибок;
- Появление новой профессии – технического писателя. Без внедрения подхода Doc as Code всей документацией на проекте занимается аналитик. Так как Doc as Code подразумевает работу с IDE и git, что не всегда входит в должностные обязанности аналитика, то выделяют отдельную должностную единицу – специалиста технического писателя.
Таким образом, отсутствие внедренного подхода Doc as Code в IT компаниях влечёт за собой ряд проблем, связанных как с управлением, так и с качеством создаваемых документов. Внедрение подхода Doc as Code позволит устранить все выявленные проблемы и даже позволит внедрить новую профессию – технического писателя.
