Семён Факторович, Константин Валеев

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

TeamLeadConf2020

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

  1. Её нет.
  2. Устаревает, не актуальная.
  3. Сложно и дорого обновлять.
  4. Непонятна нужная детальность.
  5. Непонятен процесс документирования и как он встроен в разработку.
  6. Её никто не читает, она непонятная, она сложная, получать информацию из неё дорого и долго, проще спросить устно.
  7. Её никто не пишет (в том числе потому что её никто не читает).
  8. Бизнес не очень понимает зачем нужна документация и не видят её ценность.

Как можно решить

  1. Выделить роль и, при небходимости, отдельного человека.

    Documentation Champion.

    Выделенный технический писатель в команде. Отлично работает для небольших компаний.

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

  2. Не описывать детали, которые часто меняются (см. п. 3).

    Хранить рядом с кодом. Сделать обновление документации частью критериев приёмки ревью кода.

    Поддерживать трассируемость между артефактами документации кода и тикетов.

  3. Не нужно документировать часто меняющиеся детали.

    Документировать не код, а что над ним. Документировать мотивацию — зачем нужен это код, а не что он делает. Документировать только то, что не очевидно из кода.

  4. Есть стандарты и их много. В них можно подглядывать:

  5. Определить целевую аудиторию и задачу документации — писать документацию ради документацию бессмысленно.

    Выбрать паттерн из двух: одна база знаний и множество вариантов доступа к ней или одна точка входа через агрегатор ко множеству источников. По опыту documentat.io, одна структурированная база знаний получается более жизнеспособной.

    Подумать над точками входа в базу знаний и методах поиска информации. Чем больше вариантов найти документ - тем лучше. Используйте теги, структуру, списки документов и так далее.

    Продумать структуру документации, чтобы в ней было удобно найти нужное.

    Писать несколько документов (или разделов документов) для разной целевой аудитории.

    Принять стайлгайд на тексты, писать просто и понятно. Собрать шаблоны, чтобы документация была единообразная. Примеры: redpolitika.ru.

    Линтинг качества текстов, например vale

  6. См. 0.

  7. Считать потери на отсутствие документации (например на долгий онбординг пользователей или новых сотрудников).

    Зафиксировать онбординг в терминах времени/денег.

    Опосредованно посчитать нагрузку на саппорт для пользовательской документации.

    Популяризировать профессию и роль технического писателя.

Инструменты

Минутка рекламы

Контакты: