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

  1. ДОВЕРЯЕТЕ ли вы своей текущей документации?
  2. Существует ли только один единственный источник правды для вашей документации?
  3. Легко ли найти?
  4. Легко ли построить граф зависимостей из текущей документации?
  5. Всегда ли он синхронизирован с функциями вашей кодовой базы?
  6. Легко ли понять журналы изменений или выпусков?

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

Написание документации может немного замедлить вашу индивидуальную скорость, однако с хорошей документацией вся команда или организация будут работать молниеносно ⚡.

Какие запахи у Дока? (Термин, вдохновленный запахами кода)

  1. Написание документации как отдельная задача, и в основном, глядя на код, пытаясь получить документацию.
  2. Создание нескольких копий одной и той же документации в нескольких местах. Поскольку трудно поддерживать все эти копии с небольшими изменениями.
  3. Написание документации только для одной группы.
  4. Написание документации в следующие места:
    4.a. Билеты
    4.b. Общие папки
    4.c. Sharepoints или одно примечание
    4.d. Один диск
  5. Использование неправильных тегов и меток к документу.
  6. Только разработчик или менеджер вносит свой вклад в документацию.

Все ли нужно документировать?

  1. Да, было бы неплохо сначала задокументировать его, а затем обобщить, что должно быть доступно в течение длительного времени.
  2. Если это касается нескольких заинтересованных сторон, то это должно быть задокументировано.
  3. Критическая информация, которая помогает принимать решения, должна быть задокументирована.

Дизайн должен отражать их смысл и соответствовать единообразию и стандартам.

У каждого языка есть правила грамматики, будь то английский, немецкий, шведский или любой другой. И у них есть общие вещи, такие как Тема, Глагол и Объекты, которые что-то представляют.

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

Документация что и как

Что — больше ориентировано на объяснение того, что делает продукт. Кроме того, информация доступна на README.md , wiki , docs или на внешнем веб-сайте продукта.

Пример: https://gofeatureflag.org/docs

Как — Написание CLI-программы и объяснение описания флага — это внутренняя документация, встроенная в код.

Пример: https://github.com/thomaspoignant/go-feature-flag/blob/main/config.go#L14

Точность документации

  1. Генерируется из единого источника правды.
  2. Версия контролируется.
  3. Должен быть пересмотрен.
  4. Сбой тестового кода с изменением документации.
  5. Нет лишней информации.
  6. Устаревшая информация должна быть удалена с уверенностью.
  7. Дайте ему время и напишите его полностью. Не указывайте неполную информацию и не оставляйте заполнители.

Написание тестов, документирование кода, создание блок-схем не считается развлечением. Теперь у нас осталось 2 варианта: сделать их забавными или автоматизировать.

Создание документации как увлекательное занятие

  1. Добавьте очки кармы, так как документирование кода не является частью работы, но это очень важно. Вознаграждения делают нас счастливыми, взгляните на группу Facebook, с тегами рядом с вашим именем Top Contributor мотивирует вас внести больший вклад в развитие группы.
  2. Охота на внутренние форумы и чаты, чтобы найти правильную информацию.
  3. И другие идеи будут обсуждаться в следующем посте из этой серии.

Автоматизация документации

  1. С помощью инструментов CI/CD обновляйте документацию.
  2. О том, как этого добиться, будет подробно рассказано в следующих постах.

Любопытно узнать, как документация может провалить ваши тесты. Взгляните на один из моих существующих постов о разработке, основанной на поведении:



Я новичок в разработке, основанной на поведении, с использованием Go
Бизнес и ИТ не всегда понимают друг друга. Спецификации исполняемых файлов Godog поощряют более тесное сотрудничество…levelup.gitconnected.com



Статьи в серии:

  1. Понимание проблемы

Могу ли я попросить вас любезно похлопать 👏 и поделиться ✈ публикацией, если она вам понравилась. ❤