Задать вопрос Поделиться знаниями Редактировать страницу

Встраивание фиксации знаний в процессы

В зависимости от того, что вы пишете

  • Отчётная документация

  • Архитектурная документация

  • Пользовательская документация

Встраивать фиксацию знаний в процессы приходится совсем по-разному. Но всё равно есть ряд ключевых вопросов, который нужно для себя уяснить:

  • где точка активации? — написание документов без точки активации, т.е. понимания того, как до этого документа доберутся пользователи в тот момент, когда они столкнуться с проблемой, бессмысленно.

  • как добиться, чтобы процесс не блокировался документацией? — есть соблазн требовать документацию как обязательный шаг, но в то же время фиксация знаний не должна мешать получать ценность для бизнеса. Как найти этот баланс?

  • как выстроить сам процесс документирования? Будут ли там точки с review, кто будут исполнители, будет ли оценка сроков и декомпозиция и т.п.?

Есть ли какие-то внятные материалы про то, как прорабатывать точку активации зафиксированного знания? Выглядит так, что даже пять слов, но зафиксированные в нужном месте и доступные в нужное время сильно лучше энциклопедии britannica, лежащей на полке.

Отчётная документация

Отчётная документация - т.е. использующаяся для тендеров и завершения контрактов. Как правило, она имеет малую связь с реальностью.

В написании отчётной документации ключевая проблема — это описание постфактум того, "как было сделано на самом деле", т.к. ни одно ТЗ не выполняется. Реальными знаниями обладают непосредственные исполнители, но вытащить информацию из них — не тривиальная задача.

Архитектурная документация

Архитектурная документация преследует несколько целей:

  • Более правильное принятие решений о доработках — так как всё упомнить невозможно, записи помогают охватить "думать на бумажке" и учесть ранее принятиые решения

  • Онбординг новых разработчиков

  • Упрощение поддержки

В архитектурную документацию нужно отдельно погружать сотрудников, её следует рассматривать как профессиональный инструмент, с которым нужно учить работать.

При разработке и внедрении архитектурной документации есть несколько проблем:

  • Вытаскивание информации из разработчиков — в идеале нужно интегрировать написание документации в процессы разработки и генерировать документы из кода. Для упрощения этих вопросов есть концепция Documentation-as-a-Code (продвигаемая сообществом [DocOps](https://t.me/docops)), которая близка технарям.

  • Обучение разработчиков писать связный текст — автогенерация не решает проблему связного, осмысленного текста, а лишь создаёт иллюзию наполнения контентом. Осмысленный текст разработчикам нужно учиться писать.

  • Сопротивление разработчиков — в первую очередь, в силу вышеописанной проблемы. Разработчикам тяжело писать осмысленный текст. Есть ощущение, что преодолеть его помогут чек-листы и формальные инструменты.

  • Структура архитектурной документации и навигация по этой документации

Пользовательская документация

Пользовательская документация понятна стороннему человеку и предназначена для онбрординга в проект/продукт.

Лицензия Creative Commons | by Igor Tsupko, Lana Novikova, Rodion Nagornov & community