Составляем документацию разработчика пошагово без диет и тренировок

Мы уже писали о своём опыте документирования проектов.

Теперь заход от больших ребят, в несколько другой плоскости.

Начинается статья с интересной блок-схемы, где отображены типичные вопросы по документации:
— Есть ли у вас документация?
— Актуальна ли она?
— Легко ли её найти?
— Читает ли её кто-то?
— В одном ли месте всё собрано?

В зависимости от ваших ответов на эти вопросы, автор рекомендует посмотреть те или иные пункты статьи. В них даются конкретные практические советы.

Часто полезная информация разбросана по разным источникам. Как подключиться к инфре писали в общем чате, нюансы работы с сервисом написали в личку, R&D таки зафиксировали в конфлюенс. Поэтому на первом шаге рекомендуется собрать всё вместе.

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

Чтобы понять, о чём реально стоит писать, соберите обратную связь. Прошерстите чатики, комменты под инструкциями. Если часто спрашивают, как поменять конфиги там-то — отлично, именно об этом и стоит писать.

Неочевидный, но важный момент. Вход в документацию начинается с поиска. Если где-то будет написано: кронджоба, джоба, cron, то нужный материал не найдётся. Поэтому договоритесь о единой терминологии и стиле написания. У нас, например, простое правило: любые термины пишем в их каноническом виде на английском языке.

Стоит позаботиться также о читабельности. Тут все банально — на текст должно быть приятно смотреть. В статье на этот счёт есть конкретный набор советов.

Чтобы документация читалась, и активно поддерживалась — её нужно распространять, чтобы каждый знал, куда смотреть и где искать. Недостаточно один раз скинуть ссылку в чатик и думать, что все теперь оповещены. Сообщайте о ней из всех утюгов: сделайте закрепы в общих чатах, в личных сообщениях и везде, где у вас тусуется народ.

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