Написание документации — одна из важнейших частей работы в области разработки программного обеспечения. Документация может быть написана и поддерживаться в нескольких форматах с помощью различных процедур. Тем не менее, я искренне верю, что обращаться с документацией как с кодом — это правильный путь, но как мы можем этого добиться и в чем преимущества?
Выберите язык разметки
Точно так же, как мы используем языки программирования и различные IDE для кода, мы будем использовать определенные инструменты для написания нашей документации.
Прежде всего, я очень верю в использование языков разметки для документации. Почему? Потому что он последовательный, портативный, многоразовый и его легко искать.
Для языков разметки у нас есть несколько вариантов, таких как Markdown, LaTex, reStructuredText и т. д. Мне больше всего нравится Markdown, потому что в настоящее время это просто стандарт в индустрии разработки программного обеспечения.
Используйте систему контроля версий (VCS)
Чтобы улучшить совместную работу и правильно поддерживать код, который используется несколькими инженерами, нам нужно использовать VCS, поэтому для документации будет то же самое.
Документация должна обновляться по мере роста или изменения кода, сохранение нашей документации в системе контроля версий, такой как Git, позволит нам управлять и просматривать все предыдущие версии, которые у нас были для нашей документации. Кто знает, нужно ли нам пересмотреть старую документацию или просто сбросить последние изменения в документации?
В дополнение к этому обработка добавления документации в нашу систему контроля версий посредством последовательного анализа другими инженерами улучшит качество новой документации.
Добавьте свою документацию в непрерывную интеграцию (CI)
Непрерывная интеграция (CI) — это очень важный процесс перед поставкой или развертыванием нашего кода, поскольку, помимо прочих преимуществ, он имеет высокие стандарты качества и автоматизированное тестирование.
В частности, если ваша документация будет доставлена клиентам, наличие CI является обязательным для обеспечения более высоких стандартов качества перед доставкой.
Для добавления вашей документации в процесс CI вы можете добавить несколько задач, таких как:
- Создайте свою документацию: если вы используете язык разметки, который необходимо скомпилировать, крайне важно убедиться, что ваша документация успешно построена, прежде чем ее интегрировать.
- Добавьте линтерны: наличие линтернов для вашей документации может помочь улучшить согласованность формата. Некоторыми примерами полезных линтернов могут быть lint Markdown или ReStructuredText lint.
Преимущества обращения с документацией как с кодом
Мы видели несколько процедур, которые мы применяем для кода, и которые также могут быть применены для документации.
Все эти процедуры повышают ценность нашей документации, например улучшают согласованность формата, облегчают совместную работу между несколькими людьми или устанавливают более высокие стандарты в нашей документации перед ее интеграцией.
Документация имеет одно огромное сходство с кодом, оба гниют. Это означает, что нам нужно правильно поддерживать и очищать нашу документацию как можно скорее, пока не стало слишком поздно.
Короче говоря, позаботьтесь о своей документации!