ТУЗ в рукаве
ТУЗ – Техника Управления Знаниями. Статья будет полезна в ситуации, когда ИТ документация не формализована корпоративными шаблонами и вы сами выбираете способ управления знаниями о продукте.
Приходит время, когда не код, а база знаний есть продукт. Код может написать любой, уже даже ИИ, код уже не ценность, ценность это качественная база знаний о продукте.
Почему Техника? Потому, что 10% это принципы и правила, 20% это фреймворк и 70% это личные качества и навыки человека, плюс желание делать продукты бессметными.
Цель
Цель техники – обеспечить непрерывность полноценного владения продуктом. Для этого необходимо …
- структурировать документацию;
- тщательно поддерживать полноту знаний;
- тщательно поддерживать актуальность и непротиворечивость знаний;
- улучшать понятность и выразительность текстов;
- качественно связывать знания;
- качественно форматировать знания;
- фрагментировать знания.
Концептуальные аспекты
Структурирование
Структурирование документации выполняется с целью получить иерархический каталог, который обеспечит понятное представление о структуре продукта и удобную навигацию по базе знаний.
Иерархия документов строится на принципе объектной декомпозиции. Каждый компонент (продукт, сервис, база данных и т.д.) может быть структурно декомпозирован на составляющие, которые, в свою очередь, будут представлены отдельными дочерними документами.
Компонент может быть представлен любым типом документа: паспорт, модель, индекс и т.д.
- Паспорт – содержит информацию о том, как развернуть, настроить и эксплуатировать компонент: описание конфигурационных параметров, ссылки на вспомогательные сервисы, ссылки на документы, пояснения к эксплуатационным режимам, доступы к методам API и прочий контекст.
- Модель – содержит общее структурное описание продукта, узла, компонента, приложения (диаграмма, спецификация и т.д.).
- Индекс – содержит сводный список ссылок на связанные с компонентом документы (паспорт, решение, инструкция, модель данных и т.д.)
Кроме функциональных документов (компонентов) в каталоге также будут коллекции – документы или разделы, создаваемые исключительно с целью группировки однотипных компонентов (для удобства навигации).
Кстати, между архитектурой приложения и архитектурой данных нет никакого шва. Все декомпозируется естественным образом до самой мелкой детали.
Связывание
Связывание делает базу знаний крайне удобной в использовании. Рекомендуется создавать в документах раздел Отсылки к документам, сразу после оглавления. В этом разделе рекомендуется указать полезные ссылки и ссылки, использованные в документе (исключая ссылки из таблиц). Примерный список …
- Ссылка на шаблон документа
Для удобства совершенствования шаблонов. - Ссылки на дочерние документы
Компоненты, API, GUI, концепты, модели и т.д. - Ссылки на контекст
Схемы БД, спецификации, системы, сервисы, модели, используемые решения и т.д. - Технические ссылки
Репозиторий Git, регламенты, определения, стандарты, протоколы, фреймворки, платформы, методички, опросники, полезные online сервисы, сайты продуктов, энциклопедические знания, описания паттернов решений и т.д. - Обратные ссылки
Ссылки на документы, в которых используется описанное решение.
Фрагментирование
Избегайте длинных документов, их неудобно читать, в них неудобно искать информацию, по ним неудобно разрабатывать. Разбивайте поток знаний с целью:
- сохранения целостности восприятия;
Старайтесь компактно представить концептуальные знания, длинные спецификации, коды, детальные описания выносите в дочерние документы. - избежать бойлерплейта.
Знания, которые будут использованы в нескольких документах, рекомендуется обособить и обозначить ссылкой (вместо копирования текстов).
Так как дочерним документом может быть и компонент, и фрагмент основного документа, то, чтобы не путаться, добавляете в начало заголовка специальный символ для компонентов. Символ позволит отличать декомпозицию объекта от декомпозиции документа.
Форматирование
Форматирование знаний осуществляется с помощью шаблонизации документов. Шаблон является мощным средством упаковки знаний. Шаблоны дают следующие преимущества:
- ускоряется создание однотипных документов;
Шаблон содержит памятки к разделам (например, о составе информации или способе заполнения), текстовые заготовки, структуры и прочие элементы форматирования знаний. - улучшается использование однотипных документов;
Ускоряется поиск информации, вычитывание, повышается процент усвоенной информации. - информация стандартизируется;
- снижается уровень требования к квалификации автора;
- снижается порог психологического сопротивления при подходе к новой задаче;
Принципы
При ведении документации руководствуйтесь следующими принципами …
Принцип Достаточности
Знаний должно быть достаточно, чтобы разработчик уровня Senior смог без вопросов создать и развернуть сервис. Необходимо сохранить все концептуальные знания, определяющие результат, в том числе: настройки, важные опции подключений, алгоритм процесса и его особенности, поведение в нештатных ситуациях, служебные методы, особенности развертывания и т.д. Не перегружайте документ банальными знаниями, известными опытному разработчику, это испортит восприятие важного и вызовет раздражение исполнителя.
Document First
Разработка делается не со слов аналитика или архитектора, а по документу. Сначала знания фиксируются в документе, потом создается код. Несоблюдение принципа приведет к тому, что результат станет неприятным наследием после замены сотрудника или длительного перерыва.