Documentat.io

О чем этот курс?

Docs as Code — современная технология и философия разработки технической документации. Используют ее везде: от корпораций и опенсорсных проектов мирового уровня до гаражных стартапов. Крупным командам она позволяет держать под контролем масштабные документационные проекты, небольшим — сделать документирование посильной задачей. Количество вакансий, в которых требуется владение Docs as Code, растет год от года.

Для кого этот курс?

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

Что получат слушатели?

Курс охватывает весь цикл Docs as Code — от Markdown, Visual Studio Code и архитектуры репозиториев до Git, pull request, автоматических проверок и рецензирования. На примерах Yandex Cloud, GitLab, Kubernetes, VS Code и Ubuntu слушатели научатся разбираться в устройстве документационных проектов, выбирать инструменты публикации и доводить правки до принятия. Итогом станет проверяемый практический опыт и портфолио технического писателя на GitHub.

Слушатели освоят Docs as Code на практике, разберутся в процессах и в основном инструментарии, научатся работать в команде и автоматизировать рутину. После курса вы сможете полноценно участвовать в проектах, где уже используют Docs as Code, или внедрить этот подход в своей организации.

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

1. Философия и архитектура документации как кода

Концепция документации как кода. Суть подхода «документация как код». Документация как часть инженерного процесса. Жизненный цикл документа: исходный текст, репозиторий, рецензирование, автоматическая сборка и публикация. Сильные стороны подхода: прозрачная история изменений, командная работа, проверяемость правок, связь документации с разработкой продукта. Ограничения подхода и ситуации, в которых его применение может быть избыточным.

Анатомия индустрии: разбор реальных проектов. Подходы технологических команд к документации. Структура и организация документационных проектов Yandex Cloud, GitLab, Kubernetes, VS Code и Ubuntu. Репозитории, разделы документации, навигация, правила участия, обсуждение изменений и типовые сценарии работы с документацией в открытых и корпоративных проектах.

2. Инструментарий и базовая разметка

Текстовые редакторы и среда разработки. Роль текстового редактора в Docs as Code. Отличия специализированной среды для работы с контентом от визуальных редакторов. Visual Studio Code как рабочий инструмент технического писателя: структура проекта, предпросмотр, расширения, навигация по файлам, работа с изменениями.

Базовый синтаксис разметки. Легковесные языки разметки и их роль в Docs as Code. Основные элементы Markdown: заголовки, абзацы, списки, таблицы, ссылки, изображения, выделения и блоки кода. Интерактивный предпросмотр, проверка структуры страницы и исправление типичных ошибок разметки.

3. Расширенный синтаксис и системы сборки

Диалекты и расширения разметки. Расширенный синтаксис для сложных документов. Вкладки, спойлеры, предупреждения, визуальные блоки, включаемые фрагменты и другие средства организации материалов. Различия между диалектами Markdown и расширениями конкретных движков. Ограничения переносимости материалов между разными системами публикации.

Генераторы статических сайтов. Принципы работы конвертеров, преобразующих исходники в сайт. Исходные страницы, конфигурация, маршрутизация, навигация, шаблоны и темы. Сравнительный обзор популярных конвертеров: Docusaurus, Hugo, MkDocs, Diplodoc, Sphinx и DocFX. Архитектура конфигурации проекта и маршрутизация страниц. Сильные и слабые стороны разных конвертеров и выбор подходящего инструмента для проекта.

4. Архитектура репозиториев и навигация

Структура технического репозитория. Как устроены проекты Docs as Code изнутри. Назначение служебных каталогов, конфигурационных файлов и вспомогательных ресурсов. Как по файловой структуре определить движок сборки, понять, где находятся исходные тексты, и проследить их путь до публикации на боевом сайте.

Архитектурный анализ баз знаний. Практический разбор масштабных проектов на примере Yandex Cloud, GitLab, Kubernetes, VS Code и Ubuntu. Как ориентироваться в чужой структуре разделов и читать файлы управления навигацией. Изучение различных моделей организации контента: руководства пользователя, документация для разработчиков (API), автогенерируемые справочники и версионирование материалов.

Интерфейс платформ совместной работы. GitHub и GitLab для технического писателя. Репозиторий, задача, метка, запрос на изменение, история правок, встроенный файл-менеджер, просмотр различий между версиями и обсуждение изменений. Работа с интерфейсом платформы без лишнего погружения в разработку программного кода.

5. Жизненный цикл изменений и контроль версий

Основы контроля версий для работы с текстом. Роль Git в Docs as Code. Рабочая директория, измененные файлы, подготовка изменений, commit, история правок и сравнение версий. Базовый локальный цикл: получить проект, внести изменение, посмотреть разницу, сохранить изменение в истории и подготовить его к отправке.

Работа с ветками и изменениями. Зачем в Docs as Code используют ветки. Подготовка правки в отдельной ветке, проверка состава изменения, работа с несколькими правками, предотвращение случайных изменений. Конфликты слияния в текстовых материалах и базовые способы их разрешения.

Распределенная разработка. Работа с оригинальным проектом и личной копией. Upstream, fork, локальный репозиторий и удаленный репозиторий. Синхронизация своей копии с основным проектом, отправка изменений на сервер и подготовка правки для включения в общий проект.

6. Публикация изменений и рецензирование

Процесс интеграции изменений. Жизненный цикл pull request: подготовка правки, описание изменения, автоматические проверки, обсуждение, доработка, повторная проверка и включение изменения в проект. Как написать понятное описание правки: что изменено, зачем это сделано и как проверить результат.

Автоматический контроль качества. Проверки, которые запускаются после отправки изменений. Контроль структуры, ссылок, сборки и других правил проекта. Статусы проверок, сообщения об ошибках и исправление проблем до повторной отправки на рецензирование.

Рецензирование и культура обратной связи. Как организовано профессиональное рецензирование документации. Комментарии к строкам, общие замечания, дополнительные проверки, повторное рецензирование. Взаимодействие с техническими писателями, экспертами и сопровождающими проекта. Корректная обработка замечаний и доведение правки до принятия.

7. Карьерный трек и валидация опыта

Участие в проектах как подтверждение навыка. Как использовать практику Docs as Code для развития резюме и портфолио. Проверяемый результат: ссылка на правку, история изменений, обсуждение и участие в рецензировании. Чем такой опыт отличается от общей формулировки «знаю разметку и контроль версий».

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

Упаковка опыта. Как описать полученный опыт в резюме, портфолио и сопроводительном письме. Превращение публичного профиля на GitHub в живое, проверяемое портфолио технического писателя.

Формат курса

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

Занятия проходят онлайн. Преподаватель показывает рабочий процесс на экране, после чего слушатели выполняют задания в учебном или публичном проекте. Для участия потребуются Zoom, Telegram. Список других инструментов будет опубликован заранее.