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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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