Написание документации — одна из важнейших частей работы в области разработки программного обеспечения. Документация может быть написана и поддерживаться в нескольких форматах с помощью различных процедур. Тем не менее, я искренне верю, что обращаться с документацией как с кодом — это правильный путь, но как мы можем этого добиться и в чем преимущества?

Выберите язык разметки

Точно так же, как мы используем языки программирования и различные IDE для кода, мы будем использовать определенные инструменты для написания нашей документации.

Прежде всего, я очень верю в использование языков разметки для документации. Почему? Потому что он последовательный, портативный, многоразовый и его легко искать.

Для языков разметки у нас есть несколько вариантов, таких как Markdown, LaTex, reStructuredText и т. д. Мне больше всего нравится Markdown, потому что в настоящее время это просто стандарт в индустрии разработки программного обеспечения.

Используйте систему контроля версий (VCS)

Чтобы улучшить совместную работу и правильно поддерживать код, который используется несколькими инженерами, нам нужно использовать VCS, поэтому для документации будет то же самое.

Документация должна обновляться по мере роста или изменения кода, сохранение нашей документации в системе контроля версий, такой как Git, позволит нам управлять и просматривать все предыдущие версии, которые у нас были для нашей документации. Кто знает, нужно ли нам пересмотреть старую документацию или просто сбросить последние изменения в документации?

В дополнение к этому обработка добавления документации в нашу систему контроля версий посредством последовательного анализа другими инженерами улучшит качество новой документации.

Добавьте свою документацию в непрерывную интеграцию (CI)

Непрерывная интеграция (CI) — это очень важный процесс перед поставкой или развертыванием нашего кода, поскольку, помимо прочих преимуществ, он имеет высокие стандарты качества и автоматизированное тестирование.

В частности, если ваша документация будет доставлена ​​клиентам, наличие CI является обязательным для обеспечения более высоких стандартов качества перед доставкой.

Для добавления вашей документации в процесс CI вы можете добавить несколько задач, таких как:

  • Создайте свою документацию: если вы используете язык разметки, который необходимо скомпилировать, крайне важно убедиться, что ваша документация успешно построена, прежде чем ее интегрировать.
  • Добавьте линтерны: наличие линтернов для вашей документации может помочь улучшить согласованность формата. Некоторыми примерами полезных линтернов могут быть lint Markdown или ReStructuredText lint.

Преимущества обращения с документацией как с кодом

Мы видели несколько процедур, которые мы применяем для кода, и которые также могут быть применены для документации.

Все эти процедуры повышают ценность нашей документации, например улучшают согласованность формата, облегчают совместную работу между несколькими людьми или устанавливают более высокие стандарты в нашей документации перед ее интеграцией.

Документация имеет одно огромное сходство с кодом, оба гниют. Это означает, что нам нужно правильно поддерживать и очищать нашу документацию как можно скорее, пока не стало слишком поздно.

Короче говоря, позаботьтесь о своей документации!