Документация является неотъемлемой частью цикла разработки программного обеспечения. В нем объясняется, как использовать программное обеспечение, и он может включать руководства пользователя, справочники по API, инструкции по установке и примечания к выпуску.
Автоматизация вашей документации — это последняя тенденция, поскольку она может помочь сэкономить время, уменьшить количество ошибок и обеспечить согласованность. Поддержание вашей документации в актуальном состоянии и доступность для всех заинтересованных сторон способствует совместной работе и постоянному совершенствованию.
Документы как код — это подход к автоматизации документации, при котором техническая документация рассматривается как код.
Что такое Документы как код?
Документы как код — это философия разработки программного обеспечения, которая рассматривает техническую документацию как форму кода. Это предполагает, что вы должны относиться к документации с той же строгостью и обработкой, что и программный код.
Идея документации как кода состоит в том, чтобы рассматривать документацию как первоклассный артефакт процесса разработки, интегрируя ее с жизненным циклом программного обеспечения. Это означает, что документацию следует рассматривать как неотъемлемую часть кодовой базы. Это означает применение к нему тех же процессов контроля версий, непрерывной интеграции и тестирования, что и к самому коду.
В типичной настройке docs as code вы пишете документацию в виде простых текстовых файлов, обычно в легкий язык разметки, такой как Markdown, HTML или реструктурированный текст. Затем вы сохраняете его в том же репозитории, что и исходный код. Это упрощает управление и отслеживание изменений как в программном обеспечении, так и в документации. Это также помогает убедиться, что документация соответствует последней версии кода.
Почему вы должны использовать документы в качестве кода
До того, как документы стали кодом, документация часто рассматривалась отдельно от кода, созданная с помощью других инструментов и процессов. Этот более свободный подход часто приводил к устаревшей документации и несоответствиям с кодом. Вы можете воспользоваться несколькими преимуществами, приняв документацию как подход к коду.
Улучшенное сотрудничество
Документы как код позволяют сотрудничать между разработчиками, техническими писателями и другими заинтересованными сторонами в процессе разработки. Поскольку в репозитории кода находится документация, разные стороны могут легко вносить свой вклад и вносить изменения. Это помогает обеспечить точность, актуальность и полноту документации.
Совместный подход к документации помогает гарантировать, что она включает всю необходимую информацию и точно отражает программную систему, как ее интерпретируют все стороны.
Автоматизация процессов и доступность
Еще одним преимуществом документации в виде кода является то, что она позволяет автоматическим инструментам генерировать и публиковать документацию. Система сборки может автоматически генерировать версии документации в формате HTML или PDF из текстовых файлов для публикации на веб-сайте или внутреннем портале документации. Это делает документацию доступной для большего числа заинтересованных сторон.
Автоматизируя процесс создания и публикации документации, документы в виде кода помогают сократить время и усилия, необходимые для обслуживания и публикации документации. Это позволяет командам разработчиков сосредоточиться на улучшении программного обеспечения.
Контроль версий
Хранение документации в том же репозитории кода, что и программное обеспечение, упрощает управление и отслеживание изменений в них обоих.
Вы можете использовать системы контроля версий Например, Git, чтобы отслеживать изменения в документации и при необходимости возвращаться к предыдущим версиям. Это помогает обеспечить точность и актуальность документации, а также позволяет отслеживать и проверять изменения.
Типичные документы как рабочий процесс кода
Типичный рабочий процесс «документы как код» включает в себя написание, контроль версий, сборку и размещение:
Процесс написания
Процесс написания — это первый этап типичного рабочего процесса «документы как код». Большинство технические писатели а инженеры по документации используют простой MarkDown, AsciiDoc или HTML. Они пишут документацию, используя такие инструменты, как GitBook и Redocly, которые обеспечивают плавный процесс.
Контроль версий для документации
Документация развивается по мере развития кода. Вам понадобится сложная система контроля версий, такая как Git, Plastic SCM или Subversion, чтобы отслеживать изменения в документации для упрощения совместной работы и отслеживания версий.
Процесс сборки документации
Процесс сборки включает в себя обработку и компиляцию документации в форматы доставки. Это могут быть HTML, PDF, EPUB или другие форматы. Процесс документирования обычно упрощается с помощью генераторов статических сайтов, таких как Hugo и Jekyll.
Хостинг и распространение документации
Хостинг или процесс распространения обычно является последним этапом документации как процесса кодирования. Этот процесс гарантирует, что документация будет доставлена конечному пользователю и доступна для всех заинтересованных сторон. Вы можете использовать страницы GitHub или GitLab или пользовательский портал для распространения документации в Интернете.
Вы можете автоматизировать документацию по Go и Java с помощью GoDoc и JavaDoc
Документы как философия кода произвели революцию в написании и управлении технической документацией.
Многие языки программирования, включая Go и Java, предоставляют инструменты для автоматизации документирования с помощью комментариев кода. Go предоставляет инструмент Godoc, а Java предоставляет JavaDoc.
