Documentat.io

О чем курс

О документации, которую пишут и читают разработчики: о справочниках API, о документации микросервисов, об архитектуре программных систем, о README и о процессах вокруг всего этого.

Этот курс проводится только для корпоративных групп. Количество участников — от 5 до 20 человек.

Для кого

• Для разработчиков, которые самостоятельно пишут документацию.

• Для руководителей разработки, которым нужно настроить процессы создания и поддержки документации силами разработчиков

Программа курса

• Техническая документация как форма проектной коммуникации. Когда документация лучше других способов коммуникации. Зачем и кому нужна документация. Качество документации и ее рентабельность (ROI).

• Целеполагание документации и ее целевая аудитория: зачем и кому мы пишем. Постановка задачи на создание технического документа. Профилирование целевой аудитории.

• Ревью документации. Его сходства и различия с ревью кода. Документационные стайлгайды. Связь ревью и качества документации.

• Типовые структурные ошибки в техническом тексте.

• Процессы создания и актуализации документации.

• Жанры документации для разработчиков в парадигме Diataxis: howto, tutorial, reference, explanation. Отвратительные примеры жанросмешения в документации.

• Документирование API: целеполагание, формат, структура, критерии качества. Разделение reference/howto/tutorial.

• Документирование архитектуры: целеполагание, целевые аудитории, критерии качества. Подходы из стандартов ISO/IEC/IEEE, концепции C4 и arc42. Логи архитектурных решений. Концепция ADR (Architecture Decision Record).

• Обзор современного инструментария docs-as-code. Статические генераторы Markdown/RST → HTML. Генерация PDF и DOCX.