Открыть документ в PDF · Посмотреть страницы · English summary
Я написал этот документ как пример того, как выстраиваю документацию для сложных технических процессов. Задача была такая: показать, как я подхожу к организации знаний в Confluence — не просто фиксирую факты, а строю систему, по которой любой человек в команде сможет найти нужный алгоритм, понять его логику и проследить историю изменений.
В оригинале PDF назывался «Полное описание алгоритмов в Confluence», но по факту это не описание конкретных алгоритмов — это стандарт того, как их вообще нужно документировать: какая должна быть структура страницы, какие метаданные обязательны, как выглядит жизненный цикл документа, как он связан с Jira и GitLab, и как описывать структуры данных, ошибки и производительность.
Это независимый портфолио-пример (версия 0.1). Название DVS, роли, коды ошибок и метрики нагрузки — вымышленный демонстрационный контекст, никак не связанный с реальными продуктами Atlassian, Confluence, GitLab или моими работодателями.
| Параметр | Значение |
|---|---|
| Тип документа | Руководство / стандарт ведения технической документации |
| Предмет | Алгоритмические спецификации в Confluence |
| Автор | Виктор Даниленко |
| Версия | 0.1 |
| Объём | 16 страниц, 6 глав |
| Язык | Русский с англоязычной технической терминологией |
| Целевая аудитория | Технические писатели, разработчики, архитекторы, тестировщики и аудиторы |
| Инструменты и артефакты | Confluence, Jira, GitLab, Draw.io, PlantUML, JSON Schema, Protobuf, SQL DDL |
| Формат | PDF, A4 |
Когда я работал над похожими задачами, чаще всего сталкивался с одной и той же проблемой: документация по алгоритмам либо не пишется вообще, либо каждый разработчик пишет её по-своему, и через полгода в ней невозможно разобраться. Поэтому в руководстве я постарался закрыть сразу несколько вещей:
- Confluence становится каталогом согласованных, а не черновых спецификаций.
- по документу сразу видно, кто владелец, какая версия и к какой задаче в Jira она относится.
- документацию легко сверить с кодом или схемой в GitLab.
- входные данные, логика, выходы и побочные эффекты описываются одинаково у всех алгоритмов.
- отдельно фиксируются сложность, ошибки и метрики производительности.
- видно, как менялся документ — от черновика до архива.
flowchart LR
A[Jira: задача на изменение] --> B[GitLab: код или схема]
B --> C[Confluence: draft-спецификация]
C --> D[Архитектурное ревью]
D --> E[Approved-каталог]
E --> F[Версия, аудит и архив]
F -. новое изменение .-> A
Смысл этой схемы в том, что спецификация никогда не существует сама по себе — она всегда привязана к конкретному запросу на изменение, к реализации в коде, к ревью и к истории версий.
Здесь я описываю, как устроено пространство DVS-Algorithms: шаблон страницы, обязательные метаданные (Page Properties), статусы draft, approved и deprecated, связи с Jira, GitLab, Draw.io и PlantUML, а также права доступа и аудит изменений.
Для каждого алгоритма я предусмотрел одинаковый набор блоков:
- входные данные и предварительные условия;
- шаги обработки — псевдокод или UML sequence diagram;
- выходные данные и побочные эффекты;
- временная сложность, память, CPU и I/O;
- ошибки, исключения и журналирование;
- версия и дата изменения.
Отдельно расписал, как оформлять страницы для структур данных: таблицы полей, ограничения, ссылки на JSON Schema, Protobuf и SQL DDL, кто владелец и как синхронизировать изменения.
Я предложил классификацию Business Error, System Error, Timeout и Resource Limit и свёл всё в одну таблицу кодов — с условиями возникновения, реакцией алгоритма и тем, куда это должно попадать в лог.
Здесь я собрал, какие метрики стоит фиксировать — Latency p95, Throughput, CPU Usage, RSS Memory, GC Pause, — а также параметры тестового окружения, граничные условия и вывод о соответствии SLA.
В конце — общий словарь терминов платформы и инфраструктуры: ACD, CDR, QMS, MRC, Keycloak, Patroni, Prometheus, VictoriaMetrics, RPO/RTO, TLS, SRTP и другие.
Мне важно было показать не столько сам текст, сколько подход к работе с документацией: как я проектирую информационную архитектуру, как выстраиваю повторно используемые шаблоны, как связываю документы с задачами, кодом и владельцами, как думаю о жизненном цикле страниц и версионировании, и как описываю такие вещи, как контракты данных, исключения и производительность — так, чтобы это было одинаково понятно разработке, архитектуре, QA и аудиту.
 |
 |
| Пространство DVS-Algorithms, метаданные и жизненный цикл | Входы, шаги обработки, выходы и побочные эффекты |
 |
 |
| Data Structure Template и управление изменениями | Классы ошибок, реакция алгоритма и журналирование |
Показать фрагмент глоссария
В репозитории лежит PDF со встроенными шрифтами — специально сделал так, чтобы латинские термины корректно отображались и в GitHub, и в браузере, и на Linux. Текст, структуру и пагинацию относительно исходного файла не менял.
Чтобы не было завышенных ожиданий, сразу скажу, чего здесь нет:
- это модель организации документации, а не настроенное пространство Confluence;
- макросы и процессы из документа нужно будет адаптировать под конкретную редакцию Confluence и правила вашей команды;
- метрики, коды ошибок, роли и названия компонентов — демонстрационные, не реальные;
- в репозитории нет экспортированного пространства, шаблонов Confluence, исходного кода или автоматизации GitLab/Jira;
- документ имеет версию 0.1 и должен восприниматься как портфолио-концепт, а не как готовый корпоративный стандарт.
Документ подготовил я, Виктор Даниленко, для своего профессионального портфолио. Условия просмотра и использования — в RIGHTS.md.
I wrote this as a sample of how I approach documentation governance — specifically, how to keep algorithm specs in Confluence consistent, reviewable, and traceable over time.
The guide covers a reusable algorithm page template, required metadata, lifecycle states, ownership and access rules, Jira/GitLab traceability, how to document data structures, an error catalogue, performance metrics, and a glossary. I used a fictional platform called DVS as a consistent demo context throughout.
Despite the original title, this isn't a catalogue of actual algorithms — it's a documentation standard: a way of describing algorithms so they stay controlled, reviewable, and traceable.
Author: Viktor Danilenko Version: 0.1 Language: Russian Purpose: technical writing and documentation architecture portfolio