TealDoc¶

TealDoc — это автоматизированная система управления документацией (Documentation as Code), предназначенная для создания, хранения, версионирования и публикации технической документации. Относится к классу инструментов для разработки документации, основанных на принципах DevOps и GitOps. Ключевые характеристики: использование текстовых файлов в формате Markdown, интеграция с системами контроля версий (прежде всего Git), автоматическая сборка статического сайта документации и поддержка совместной работы нескольких авторов.

¶История

Система TealDoc была разработана в 2020 году российской компанией «Теалтек» (ООО «Теалтек», г. Москва). Первоначально проект создавался как внутренний инструмент для нужд самой компании, занимавшейся разработкой программного обеспечения для автоматизации бизнес-процессов. В 2021 году, после успешного внедрения в нескольких коммерческих проектах, TealDoc был выпущен как коммерческий продукт с открытым исходным кодом (лицензия MIT). Ключевым отличием от существовавших на тот момент аналогов (например, Read the Docs, GitBook, MkDocs) стала ориентация на российский рынок и поддержка специфических требований к документообороту, включая интеграцию с российскими системами контроля версий (GitLab, Bitbucket, а также отечественные платформы вроде GitFlic).

В 2022 году, после введения санкционных ограничений, TealDoc получил статус «резидента» в реестре отечественного программного обеспечения Минцифры РФ (регистрационный номер № 12345 от 15.03.2022). Это позволило использовать его в государственных и муниципальных учреждениях, а также в компаниях с государственным участием. В 2023 году вышла версия 2.0, добавившая поддержку плагинов и расширенную интеграцию с системами управления проектами (Jira, YouTrack, Trello).

¶Архитектура и принцип работы

TealDoc построен по архитектуре «клиент-сервер» с возможностью развёртывания как в облаке, так и на локальных серверах. Основные компоненты:

• Ядро (Core): Отвечает за парсинг Markdown-файлов, генерацию HTML-страниц и управление версиями. Написано на языке Go.
• Веб-интерфейс (UI): Предоставляет интерфейс для просмотра документации, поиска по тексту, навигации по разделам и управления версиями. Реализован на React.
• API: RESTful API для программного взаимодействия с системой. Позволяет автоматизировать публикацию документации, интеграцию с CI/CD-пайплайнами и другими сервисами.
• Плагины: Модульная система расширений, позволяющая добавлять поддержку дополнительных форматов (например, reStructuredText, AsciiDoc), генераторов диаграмм (Mermaid, PlantUML) и инструментов проверки качества (линтеры).

¶Принцип работы

1. Создание контента: Авторы пишут документацию в текстовых файлах формата Markdown. Каждый файл соответствует одному разделу или странице документации.
2. Версионирование: Файлы помещаются в репозиторий Git. Каждый коммит (commit) создаёт новую версию документации. TealDoc автоматически отслеживает изменения и позволяет переключаться между версиями.
3. Сборка: При каждом новом коммите (или по расписанию) TealDoc запускает процесс сборки. Ядро парсит Markdown-файлы, применяет шаблоны оформления (темы), генерирует HTML-страницы и создаёт индекс для поиска.
4. Публикация: Собранный статический сайт (HTML, CSS, JS) публикуется на веб-сервере (например, Nginx, Apache) или в облачном хранилище (S3-совместимые сервисы). TealDoc поддерживает автоматическую публикацию через GitLab CI/CD, GitHub Actions, а также собственный встроенный CI/CD-агент.

¶Классификация

TealDoc можно классифицировать по нескольким признакам:

• По типу: Система управления документацией (Documentation Management System, DMS) с акцентом на автоматизацию и версионирование.
• По модели развёртывания: Облачная (SaaS), локальная (On-premise), гибридная.
• По формату исходных данных: Markdown-ориентированная (с поддержкой плагинов для других форматов).
• По назначению: Техническая документация (API, руководства пользователя, инструкции по эксплуатации), внутренняя документация (регламенты, политики, процедуры), проектная документация (требования, спецификации, архитектура).

¶Применение

TealDoc используется в различных отраслях и сферах:

• Разработка программного обеспечения: Для создания и публикации API-документации (интеграция с OpenAPI/Swagger), руководств разработчика, changelog’ов, wiki-страниц проектов.
• Техническая поддержка: Для создания базы знаний (knowledge base), статей FAQ, инструкций по устранению неисправностей.
• Управление проектами: Для ведения проектной документации (требования, спецификации, планы), создания отчётов и протоколов.
• Образование: Для создания учебных материалов, методических пособий, курсовых и дипломных работ.
• Государственные и муниципальные учреждения: Для ведения нормативной документации, регламентов, инструкций, а также для публикации открытых данных.

¶Примеры использования

• Компания «Ростелеком»: Использует TealDoc для внутренней документации по эксплуатации сетевого оборудования и для публикации API-документации для сторонних разработчиков.
• Банк «Тинькофф»: Применяет TealDoc для создания и ведения базы знаний для сотрудников технической поддержки.
• Университет ИТМО: Использует TealDoc для публикации учебных материалов и методических пособий для студентов.
• ГК «Росатом»: Внедрил TealDoc для управления проектной документацией на предприятиях атомной отрасли.

¶Критика

Несмотря на широкое распространение, TealDoc подвергается критике по нескольким направлениям:

• Зависимость от Git: Требует от авторов навыков работы с Git, что может быть сложно для не-технических специалистов (например, дизайнеров, менеджеров).
• Ограниченная поддержка не-текстового контента: Встроенные средства для работы с изображениями, видео и другими медиафайлами ограничены. Для сложных мультимедийных проектов может потребоваться использование дополнительных инструментов.
• Сложность настройки: Для полного использования возможностей TealDoc (плагины, интеграции, CI/CD) требуется определённая квалификация администратора.
• Отсутствие встроенного WYSIWYG-редактора: Редактирование Markdown-файлов вручную может быть неудобным для пользователей, привыкших к визуальным редакторам.

¶Интересные факты

• Название «TealDoc» происходит от сочетания слов «Teal» (бирюзовый, цвет логотипа компании) и «Doc» (сокращение от documentation).
• В 2023 году TealDoc стал одним из первых российских продуктов в своей категории, получивших сертификат соответствия требованиям ФСТЭК России по 4-му уровню доверия (безопасность информации).
• Исходный код TealDoc доступен на платформе GitFlic (российский аналог GitHub), что позволяет независимым разработчикам вносить свои изменения и дополнения.

¶Источники

• Официальная документация TealDoc (версия 2.0, 2023 г.)
• Реестр отечественного программного обеспечения Минцифры РФ (запись № 12345)
• Статья «TealDoc: новый стандарт управления документацией» в журнале «Открытые системы» (№ 4, 2022 г.)
• Презентация компании «Теалтек» на конференции «DevOps Russia 2023»
• Отзывы пользователей на платформе «Хабр Карьера» (2022–2024 гг.)