{"id":13831,"url":"\/distributions\/13831\/click?bit=1&hash=c8aa181d335f39dea37c6371ff973049ca181b1a0115b2c21b8b33ac2ce446e9","title":"\u0420\u0430\u0437\u0434\u0430\u0451\u043c \u043c\u0435\u0434\u0430\u043b\u044c\u043a\u0438 \u0437\u0430 \u0438\u043d\u0432\u0435\u0441\u0442-\u0434\u043e\u0441\u0442\u0438\u0436\u0435\u043d\u0438\u044f. \u0421\u043a\u043e\u043b\u044c\u043a\u043e \u043f\u043e\u043b\u0443\u0447\u0438\u0442\u0435 \u0432\u044b?","buttonText":"\u041f\u0440\u043e\u0432\u0435\u0440\u0438\u0442\u044c","imageUuid":"b1525eff-10a7-5057-afd4-3762e3fb4a3d","isPaidAndBannersEnabled":false}

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

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

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

Общие рекомендации

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

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

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

Правила организации структуры документов

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

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

• Объект • Паспорт • Спецификация А • Компоненты • Базы данных • База А • Паспорт • База Б • Паспорт • Загрузчики • Загрузчик А • Паспорт • Загрузчик Б • Паспорт • Решения • Коробки • Контекст

Элементы структуры

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

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

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

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

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

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

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

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

Комментарии

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

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

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

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

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

0
Комментарии
Читать все 0 комментариев
null