Ведение документации

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

В этой статье я публикую часть документа, обучающего искусству владения знаниями (система хранения знаний - Confluence).

Создавайте в документах раздел Связанные документы, в этом разделе рекомендуется собирать все ссылки (исключая ссылки, которые приводятся в специальных ссылочных столбцах таблиц), указанные в документе. Делается это для удобства пользования документом читателями.

Все документы снабжайте ссылкой на шаблон, для удобства постоянного совершенствования шаблонов.

Основные разделы документа снабжайте подсказкой, из которой можно узнать характер и состав информации, помещаемой в раздел.

Структура документов строится на принципе объектной декомпозиции. Каждый компонент (продукт, сервис, база данных и т.д.) может быть структурно декомпозирован на составляющие, которые, в свою очередь, будут представлены отдельными документами. Глубина декомпозиции определяется автором самостоятельно. Если описываемый объект/компонент далее не декомпозируется, то для него не нужно создавать полноценную структуру, поясняемую ниже.

Типовые элементы документной структуры объекта выглядят так ...

Объект (База A/Б, Загрузчик A/Б)
Корневой документ объекта/компонента.

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

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

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

Коробки
Корневой документ для списка тиражируемых компонентов (т.е. используемых в Объекте многократно). Тиражируемым может быть: коробочный компонент (экземпляры конфигурируются настройками), заготовка или полуфабрикат (экземпляры получаются с помощью незначительной доработки) и т.д. Для каждого экземпляра тиражного компонента должна быть создана отдельная документация в разделе Компоненты, где описана индивидуальная конфигурация экземпляра или суть доработки до полноценного изделия.

Контекст
Корневой документ для описания внешних систем и служб, взаимодействующих с объектом.

расширения (Спецификация А)
Подчиненный документ, по сути - обособленная часть информации из основного документа. Подчиненные документы рекомендуется использовать, чтобы не разрушать целостность восприятия основного документа. В подчиненные документы выносится детальная информация из за её значительного объема.

группировки (Базы данных, Загрузчики)
Подчиненные документы, созданные исключительно с целью группировки и удобства навигации однотипных компонентов.

К стандартным именам (Компоненты, Решения, Коробки, Паспорт и т.д.) документов необходимо добавлять символ # и символические коды родительских страниц. Это связано с ограничением Confluence, которое обязывает все документы в пространстве снабжать уникальным именем (заголовком).

Обратите внимание, сама структура определяет только способ каталогизации документов. Анатомия какого-либо решения всегда индивидуальная, посмотрите на примере ETL-сервиса.

• Паспорт на экземпляр сервиса содержит в основном: перечень настроек и требования к подключению средств мониторинга. Сам же сервис разворачивается на базе коробочного (тиражируемого) решения. В паспорте использован внешний документ - спецификация потока.
• Коробочное решение содержит в основном: бизнес-требования, описание загрузок конфигурационных данных, сохранений логов и разных форматов. Реализация же механики работы сервиса описана в отдельном документе - концепт сервиса.
• Концепт сервиса является самостоятельным документом (условно-первичным), который, в свою очередь, использует описание трех методик.

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

Все эти документы компактны, читабельны, связаны между собой и разложены в структуре, описанной выше.