Привет!
Я знаю, как многим тяжело начинать большое дело в понедельник. Поэтому я специально протянул время аж до среды)
Итак, торжественное открытие курса Docs as code для самых маленьких считаем состоявшимся и переходим к делу.
Сегодня нас ждёт самое сложное: целый пост сухой теории. Вообще я не методолог, поэтому постараемся кратко и по существу.
Что такое docs as code и зачем он нужен?
Docs as code — это подход к разработке документации, который основан на принципах и практиках работы с кодом.
Это значит, что при работе с документацией мы пользуемся процессами и инструментами разработки кода:
1. Пишем доки на облегчённом языке разметки
Не бойтесь! Писать будем на русском языке) А вот форматировать текст — с помощью легковесной разметки.
Синтаксис облегчённого языка разметки состоит из наборов символов, которые используются для разметки неформатированного текста. Вы можете работать с облегчённым языком разметки в любом редакторе (хоть в блокноте), и ваш текст будет легко читаться безо всякой обработки. Файлы, написанные с помощью языка разметки, легко сконвертировать во что-то более красивое и стильное (например, в html). В рамках нашего курса мы будем использовать Markdown как один из самых популярных облегчённых языков разметки.
2. Храним документацию в системе контроля версий
Система контроля версий — это программное обеспечение для организации работы с регулярно обновляющимися данными. Мы можем хранить разные версии одних и тех же файлов, вносить изменения в файлы параллельно с коллегами без потери чужих правок, откатываться к старым стабильным версиям и создавать новые. Использование системы контроля версий — это стандарт для хранения кода и работы с ним. В docs as code мы перенимаем этот опыт для управления исходными файлами нашей документации.
Самая популярная на сегодня система контроля версий — GIT, которой мы и будем пользоваться.
3. Проводим ревью документации
Ревью — это классическая часть процесса разработки документации независимо от того, используем мы docs as code или нет. Но здесь мы будем проводить ревью с помощью функциональности GIT и делать это также, как делают разработчики.
4. Собираем и публикуем документацию
Облегченные языки разметки — это очень хорошо и удобно, но пользователи доки хотят видеть красивую доку, а не эти ваши разметки. Поэтому, также, как программисты собирают свой код в симпатичное работающее приложение, мы собираем свои файлы симпатичный работающий документационный портал. Тут может быть несколько вариантов, но мы пойдём по классике и будем собирать статичный сайт с помощью генератора сайтов, а потом настроим автоматическую публикацию этого сайта через GitHub (сервис для хранения исходников и работы с гит).
Использование docs as code должно иметь цель. Для себя я сформулировал её так:
Вроде всё, получилось вполне коротко 🫣
Ура! Теории больше не будет! Только практические задания, только качественный гранж! (не люблю хардкор)
Оставайтесь на линии)
#практика #docsascode
Я знаю, как многим тяжело начинать большое дело в понедельник. Поэтому я специально протянул время аж до среды)
Итак, торжественное открытие курса Docs as code для самых маленьких считаем состоявшимся и переходим к делу.
Сегодня нас ждёт самое сложное: целый пост сухой теории. Вообще я не методолог, поэтому постараемся кратко и по существу.
Что такое docs as code и зачем он нужен?
Docs as code — это подход к разработке документации, который основан на принципах и практиках работы с кодом.
Это значит, что при работе с документацией мы пользуемся процессами и инструментами разработки кода:
1. Пишем доки на облегчённом языке разметки
Не бойтесь! Писать будем на русском языке) А вот форматировать текст — с помощью легковесной разметки.
Синтаксис облегчённого языка разметки состоит из наборов символов, которые используются для разметки неформатированного текста. Вы можете работать с облегчённым языком разметки в любом редакторе (хоть в блокноте), и ваш текст будет легко читаться безо всякой обработки. Файлы, написанные с помощью языка разметки, легко сконвертировать во что-то более красивое и стильное (например, в html). В рамках нашего курса мы будем использовать Markdown как один из самых популярных облегчённых языков разметки.
2. Храним документацию в системе контроля версий
Система контроля версий — это программное обеспечение для организации работы с регулярно обновляющимися данными. Мы можем хранить разные версии одних и тех же файлов, вносить изменения в файлы параллельно с коллегами без потери чужих правок, откатываться к старым стабильным версиям и создавать новые. Использование системы контроля версий — это стандарт для хранения кода и работы с ним. В docs as code мы перенимаем этот опыт для управления исходными файлами нашей документации.
Самая популярная на сегодня система контроля версий — GIT, которой мы и будем пользоваться.
3. Проводим ревью документации
Ревью — это классическая часть процесса разработки документации независимо от того, используем мы docs as code или нет. Но здесь мы будем проводить ревью с помощью функциональности GIT и делать это также, как делают разработчики.
4. Собираем и публикуем документацию
Облегченные языки разметки — это очень хорошо и удобно, но пользователи доки хотят видеть красивую доку, а не эти ваши разметки. Поэтому, также, как программисты собирают свой код в симпатичное работающее приложение, мы собираем свои файлы симпатичный работающий документационный портал. Тут может быть несколько вариантов, но мы пойдём по классике и будем собирать статичный сайт с помощью генератора сайтов, а потом настроим автоматическую публикацию этого сайта через GitHub (сервис для хранения исходников и работы с гит).
Использование docs as code должно иметь цель. Для себя я сформулировал её так:
Создание культуры документирования с прозрачными процессами разработки документации, интегрированными в общие процессы работы продуктовой команды.
Вроде всё, получилось вполне коротко 🫣
Ура! Теории больше не будет! Только практические задания, только качественный гранж! (не люблю хардкор)
Оставайтесь на линии)
#практика #docsascode