Это конспект с митапа про документацию на РИТ++ 2018. Провели и записали Семён Факторович и Николай Волынкин.
Техписатели и разработчики по-разному смотрят на процесс и на решения. Давайте дружить и сотрудничать! Мир, труд, девопс!
Хотите дополнить — редактируйте и кидайте пуллреквест.
Содержание
Митапы сообщества технических писателей:
Телеграм:
Консультирование и обучение
Презентация о документировании разработки мобильных приложений с митапа от Славы Черникова.
Документация Ansible:
- Почему некому писать? Как обосновать нужность техписателя и его работы? Какие роли нужны в создании документации? Как определить зоны ответственности?
- Что входит в необходимый набор документации для технарей: разработчиков, тестировщиков, эксплуатации?
- Как писать для разных аудиторий?
- Как сохранять знания о коде и архитектуре, как передавать их?
- Как актуализировать документацию, кто будет это делать?
- Как работать с подрядчиками: кто будет писать доки и когда, как обеспечить качество?
- Особенности процесса в Agile.
- Критерии качества и актуальности, лучше если автоматизируемые.
- Интеграция между командами и компонентами.
Два заблуждения:
-
Нам кажется, что мы полностью представляем весь объем знаний о проекте/продукте.
На самом деле нет.
-
Нам кажется, что можно определить нужную глубину описания для конкретной аудитории.
Тоже скорее всего нет.
Выход:
-
Документация пишется для того, чтобы кто-то решил свою проблему.
Проанализируйте, что аудитория знает и что не знает.
-
Зачем вы пишете документацию? Что будет, если её не написать? Есть два аспекта:
- На уровне пользователя. Какую свою проблему он хочет решить?
- На уровне бизнеса. Какую задачу бизнеса решает документация? Какой будет нагрузка на саппорт, если документация не решит проблему? Здесь важна аналитика.
Это даёт ответ на вопрос, что именно нужно описывать.
Следующий этап — четко формулировать шаблоны и типичные документы. Например, «описание фичи для маркетинга». Шаблоны итеративно улучшать. В результате появятся критерии качества: можно будет определить, насколько документ соответствует целям.
Результат: внутренний корпоративный документационный стандарт. Когда он есть, можно его же предлагать подрядчикам.
Ещё в стандарт входит жизненный цикл документа. Как он разрабатывается, через каких специалистов проходит: эксперт в предметной области, ещё один техписатель для ревью языка, дизайнер и т.п.
Есть общие стандарты, например ГОСТ-19 и ГОСТ-34. Их полезно использовать, только если это бизнесовое требование.
Есть англоязычные стандарты. Полезно их почитать и извлечь конкретные приемы.
- ISO/IEC/IEEE 12207 Software Life Cycle Processes
- ISO/IEC/IEEE 26515 Developing User Documentation in an Agile Environment
- ISO/IEC/IEEE 26511 Requirements for Managers of User Documentation
- ISO/IEC/IEEE 26512 Requirements for Acquirers and Suppliers of User Documentation
- ISO/IEC/IEEE 26513 Requirements for Testers and Reviewers of User Documentation
- ISO/IEC/IEEE 26514 Requirements for Designers and Developers of User Documentation
Есть объективные и субъективные критерии. Субъективные возражения не пройдут, их легко оспорить. Нужно искать объективные критерии и фиксировать их при постановке задачи на создание документа
Удобно, когда документация в репозитории:
- Легковесная разметка (Markdown, reStructuredText)
- Генератор статических сайтов (Jekyll, Hugo, Sphinx)
- Собираем и деплоим вместе с продуктом
Можем добавить проверку, что если поменялся код, то должна поменяться и документация. GitHub позволяет назначить владельцев кода в конкретной папке — назначьте писателя и продакта/аналитика. Первый проверит язык, второй — суть.
Поддерживаем актуальность: внедряем актуализацию документа в рабочий процесс разработки фичи.
Иногда дешевле дропнуть доку и написать новую. Или даже не писать. Например, из конфлюенса нужно регулярно выбрасывать устаревшие статьи, уменьшая количество документации. Это ещё и улучшает результаты поиска.
Бывает To Be и As Is
Не стоит описывать to be досконально — разработчик часто лучше знает, как сделать. Достаточно зафиксировать важные требования.
- облегчает онбоардинг
- не обязательно описывать, как всё сделано — это есть в коде.
- инфа, которой в коде нет — почему всё сделано именно так?
Документация пишется долго
- Первичный цикл (послушали программиста — написали — отдали ему на вычитку) занимает много времени из-за когнитивных искажений
- Даже квалифицированный техпис пишет достаточно долго (структурирование информации — сложный процесс)
Вариант для старта: когда не успеваем документировать, сделать видео или аудиозапись, как человек рассказывает про систему.
Для примеров кода и API видеозаписи подходят плохо.
Хорошо для разработчиков этого же кода, не подходит для интеграции.
Для интеграции полезны написанные докстринги. В них стоит написать про контракт метода, предусловия, постусловия.
Проблема: техпис пишет технически неточно. Не хватает экспертизы в предметной области.
Решение: смотреть на то, как понимают целевые читатели. Понимают ли они? Каков путь до первого Hello World, сколько процентов добираются? Если добираются, то можно допустить, что разработчик с чем-то не согласен.
Пример: точный и бесполезный man git, неточный и полезный Learn Git Branching.
Если приходится писать слишком сложно, возможно фича сделана плохо — не в терминах проблемы.
Презентация от Славы Черникова
- Архитектура проекта
- Единая терминология
- Структура экранов
- Структура переходов
По шагам:
-
Разбиваем экраны на разделы и даем названия
-
Выстраиваем правильную структуру. Convention over configuration.
-
Рисуем карту переходов.
Традиционные карт делаются дизайнерами для дизайнеров. Они неудобны.
Можно показывать передаваемые на экран данные и источник перехода.
-
Таблица: выжимка ключевых данных по каждому переходу.
Вполне возможен реверс-инжиниринг внутренней документации для легаси-кода, т.е. создание ее с нуля. Неплохой вариант — целить такой документацией и в разработчиков, и в тестировщиков (чтобы помочь им с тест-кейсами).
Для крупных легаси-систем лучше идти итеративно, описывать по частям и с небольшой глубиной погружения.
А еще бывает легаси-документация — устаревшая (и непонятно, актуальная ли) документация для устаревшего кода. Часто, проще ее выкинуть, но она может содержать ценную и сложно восстанавливаемую информацию.