Семён Факторович, Николай Волынкин

Как сделать так, чтобы документация не болела

HighLoad2019

Конспект митапа на Highload++ Siberia 2019.

Ведущие:

Определимся с терминами

Мы по профессии техписатели, и у нас своя специфика трактовки термина «документация».

Техписатели традиционно занимаются той документацией, которая пишется после написания кода — справочники API, руководства пользователя, описание архитектуры и дизайн-решений.

Документация, которая пишется до написания кода (ТЗ, спецификации требований), в нашей картине мира — область ответственности системных аналитиков.

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

В архитектурной документации есть такое же разделение: есть доки «как мы хотим сделать» и доки «как мы сделали».

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

Примеры документации из практики участников митапа:

Формальное определение документации

Идем в PMBOK, Project management body of knowledge.

В проекте есть стейкхолдеры и коммуникации между ними. Аналитики передают информацию разработчикам, пользователи API забирают информацию тоже у разработчиков, потенциальные клиенты имеют вопросы к product owner’ам.

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

Что бывает не так с документацией

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

Следствия отсутствия документации:

Сложно структурировать

Документация устарела или ошибочна

Написана так, что извлекать информацию сложно

Обобщая: документация очень часто не решает задачи принимающего стейкхолдера (неполна, ошибочна, написана для решения другой проблемы).

Пользователь не хочет читать

Документация низкоприоритетна.

Обычно в команде разработки есть что ещё поделать. Свободное время идёт на техдолг.

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

Что с этим делать

Тезисно

  1. Четкое понимание, каких двух стейкхолдеров связывает документация, и какую проблему принимающей стороны мы решаем.

  2. Инструментальный стек и инструментальные сценарии.

    • «Чтобы задокументировать API для очередного микросервиса, мы берем OpenAPI и коммитим сваггер-файл вот сюда, назвав его по такой-то конвенции»
    • «Дизайн-решения по компонентам мы описываем в Confluence и складываем вот сюда»

  3. Шаблоны и эталонные примеры документации для повторяемых объектов документирования.

  4. Критерии качества и процедуры проверки (как мы проверяем, что в документации нет ошибок? а как мы проверяем, что она полна?)

  5. Четкое место документации в цикле разработки. Документация — часть definition of done фичи.

  6. Четкие процессы поддержания документации в актуальном состоянии. Нельзя пофиксать баг, не обновив всю релевантную документацию (и не прогнав QA-процесс, подтверждающий, что она действительно обновлена).

  7. Documentation owner или documentation champion: человек, которому больше всех не пофиг на документацию, который видит и чувствует, как она должна жить и выглядеть, и у которого есть административные рычаги внедрить пп.1-6 выше или продать все это высшему менеджменту.

Инструментальный стек

Есть барьер на написание документации, во многом психологический. Неясно, как начать.

Решение:

Роль документации в общем цикле разработки

Если строгого процесса нет, то его нет вообще.

Вопросы

Актуализация доки в Swagger

Можно считать coverage с помощью Cucumber, проверять что не уменьшилось

Визуализация диаграмм

Есть сложная процессная диаграмма с несколькими представлениями. Как сделать ее читаемой?

Человек выходит к чистой доске, рисует диаграмму с нуля и рассказывает. Всё это записываем на видео.

Внятная opensource-документация

Есть опенсорсный продукт. Можно описать всё, но это слишком много. Можно описать часть. Пользователи:

Решение: посмотреть на практики больших опенсорсных продуктов, например Google Protobuf. Для новых пользователей делать отдельную документацию. Необязательно текст, можно видео, доклады на конференциях, что угодно. Строим «лесенки» для новых пользователей, по которым они могут зайти в продукт.

Контекстуальность документации

Документация от программистов к программистам очень часто «прячет лес за деревьями»: детали заглушают общую картину. Как надо: «описываемая система — это…, она нужна, чтобы … и позволит вам сделать…».

«Прочитав этот документ, вы сможете…», «по завершению этого документа у вас будет…», «этот документ расчитывает, что вы знаете…»

Что почитать и посмотреть

Книга «Пиши, сокращай» Ильяхова и Сарычевой

KnowledgeConf (апрель 2019), доклад Alexandrа White про видеодокументацию.

Линтеры для документации: testthedocs.org

Курс по документированию API: Tom Johnson, Documenting APIs

Продукты с хорошей документацией

Ещё хорошие практики