Добро пожаловать в Docs-as-Code Portfolio
Этот сайт — демонстрация подхода Docs-as-Code в действии. Здесь вы найдёте примеры документации, созданной с использованием современных инструментов и процессов, принятых в разработке программного обеспечения.
Что такое Docs-as-Code?
Docs-as-Code (документация как код) — это методология, при которой техническая документация создаётся, хранится и публикуется с использованием тех же инструментов и процессов, что и исходный код.
Ключевые принципы
| Принцип | Реализация |
|---|---|
| Единый источник правды | Документация хранится в том же репозитории, что и код |
| Контроль версий | Git отслеживает все изменения, как в коде |
| Ревью через pull requests | Документация проходит проверку перед публикацией |
| Автоматическая сборка | CI/CD собирает и публикует документацию при каждом изменении |
| Изолированное окружение | Docker гарантирует воспроизводимость сборки |
Инструменты, используемые в этом проекте
- Markdown — язык разметки для написания документации.
- MkDocs + Material for MkDocs — генератор статического сайта.
- Docker — изолированная среда сборки.
- GitHub Actions / GitVerse CI — автоматизация сборки и публикации.
- Mermaid — диаграммы прямо в тексте.
- markdownlint — проверка стиля Markdown.
- OpenAPI — описание REST API.
Что вы найдёте в этом портфолио
Примеры документации
- Быстрый старт — как начать работу с проектом.
- Руководство по установке — пошаговая инструкция.
- Руководство по настройке — конфигурация системы.
- Руководство по интеграции — подключение внешних сервисов.
- Устранение неполадок — решение частых проблем.
- API Reference — документация REST API (OpenAPI).
Процессы и стандарты
- Стайлгайд — правила оформления документации.
- Чек-лист ревью — как проверяется документация.
Как это работает
- Автор пишет документацию в Markdown и коммитит в Git.
- CI/CD автоматически запускает линтеры и собирает сайт.
- Ревьюер проверяет изменения через pull request.
- После мержа документация публикуется на сайте.
Контакты
- Автор: Милько Дмитрий Иванович
- Email: profdefence@mail.ru
- Telegram: @Dmilkoff
- Сайт: profdefence.ru
Этот сайт собран автоматически из Markdown-файлов с помощью MkDocs и опубликован через CI/CD.