Как правило, документация не особо интересна разработчикам, но без их помощи документ может быть неточным, неполным и непонятным. Как привлечь разработчика к созданию документа?
Как правило, документация не особо интересна разработчикам, но без их помощи документ может быть неточным, неполным и непонятным. Как привлечь разработчика к созданию документа? Предоставить документацию на понятном ему языке, а именно, документацию в виде кода.
Docs as Code представляет собой подход к разработке программной документации с использованием тех же инструментов, что и для написания кода. Как это происходит? Разработка документа осуществляется при помощи упрощенного языка разметки (Markdown, reStructuredText, Asciidoc). Для хранения документации используются репозитории Git (GitHub и GitLab), что позволяет отслеживать изменения и контролировать версии. Сбор документации в различные форматы происходит при помощи генераторов статических сайтов.
Данный подход отличает ряд преимуществ:
- заинтересованность разработчика в процессе подготовки документа;
- версионность;
- высокая скорость загрузки сайта;
- простота публикации;
- доступность.
Зачастую организация не может позволить себе нанимать технического писателя. В таком случае документы подготавливают разработчики. Использование понятного и удобного подхода значительно повышает их интерес, а значит и документация будет более точной и качественной.
Хранение документов в репозиториях Git позволяет непрерывно обновлять в них информацию. Изменения в документах отображаются за долю секунды. Представим, что мы для внесения коррективов пересылаем документ в формате DOCX. Сколько бы это заняло времени? Значительно дольше. К тому же, контроль над изменениями в таком случае не автоматизирован. Доверять придется исключительно внимательности участников процесса разработки документации.
Многостраничный файл в формате PDF может загружаться несколько минут, что довольно долго относительно сайтов с подходом Docs as Code. Страницы сайтов открываются мгновенно, что ускоряет время подготовки программного документа в целом.
Бывает, что документацию необходимо разместить в онлайн-формате. В таком случае публикация документа представляет собой долгий и многоступенчатый процесс. Размещение же документа в онлайне при подходе Docs as Code может быть полностью автоматизировано или сведено к одной команде.
Бесспорным плюсом Docs as Code является его доступность. Процесс разработки и размещения документации в целом бесплатный. Потратиться придется только на расширение возможностей в GitHub или GitLab (увеличение объема для хранения и обеспечение защиты информации).
К недостаткам рассматриваемого подхода относятся:
- необходимость настройки системы;
- отсутствие технической поддержки;
- высокие требования к навыкам технического писателя;
- сложность работы с языками разметки.
В данном случае готовая версия продукта отсутствует. Все необходимые инструменты для разработки документов нужно настраивать вручную. Совершенствование системы публикации займет время и потребует привлечения специалистов. Также при данном подходе отсутствует техническая поддержка. Во всех неполадках системы придется разбираться самостоятельно.
Техническим писателям необходимо освоить работу с Git. Для этого можно предложить им пройти специализированный курс по освоению Git или предоставить ряд материалов для самостоятельного обучения. Проблема хоть и решаемая, но требующая финансовых и временных затрат.
Не всем удобно использовать языки разметки. Разработчики привыкли к подобной форме информации. Технические писатели, в свою очередь, зачастую прибегают к помощи WYSIWYG-редакторов. Очевидно, что им потребуется время, чтобы привыкнуть к новой для себя форме. К тому же, необходимо будет выучить синтаксис выбранного языка.
Подход Docs as Code позволит ускорить и упростить процесс разработки программной документации. Обучив технических писателей работе с Git и специфике различных языков разметки, можно сократить до минимума трудоемкость их работы.