Задать вопрос Поделиться знаниями Редактировать страницу
Встраивание фиксации знаний в процессы
В зависимости от того, что вы пишете:
-
отчётная документация
-
Архитектурная документация
-
Пользовательская документация
встраивать фиксацию знаний в процессы приходится совсем по-разному. Но всё равно есть ряд ключевых вопросов, который нужно для себя уяснить:
-
Где точка активации? Написание документов без точки активации, т.е. понимания того, как до этого документа доберутся пользователи в тот момент, когда они столкнутся с проблемой — бессмысленно.
-
Как добиться, чтобы процесс не блокировался документацией? Есть соблазн требовать документацию как обязательный шаг, но в то же время фиксация знаний не должна мешать получать ценность для бизнеса. Как найти этот баланс?
-
Как выстроить сам процесс документирования? Будут ли там точки с review, кто будут исполнители, будет ли оценка сроков и декомпозиция, и т.п.?
| Есть ли какие-то внятные материалы про то, как прорабатывать точку активации зафиксированного знания? Выглядит так, что даже пять слов, но зафиксированные в нужном месте и доступные в нужное время сильно лучше энциклопедии britannica, лежащей на полке. |
Отчётная документация
Отчётная документация — т.е. использующаяся для тендеров и завершения контрактов. Как правило, она имеет малую связь с реальностью.
В написании отчётной документации ключевая проблема — это описание постфактум того, "как было сделано на самом деле", т.к. ни одно ТЗ не выполняется. Реальными знаниями обладают непосредственные исполнители, но вытащить информацию из них — нетривиальная задача.
Архитектурная документация
Архитектурная документация преследует несколько целей:
-
Более правильное принятие решений о доработках — так как всё запомнить невозможно, записи помогают "думать на бумажке" и учесть ранее принятиые решения
-
Онбординг новых разработчиков
-
Упрощение поддержки
В архитектурную документацию нужно отдельно погружать сотрудников, её следует рассматривать как профессиональный инструмент, с которым нужно учить работать.
При разработке и внедрении архитектурной документации есть несколько проблем:
-
Вытаскивание информации из разработчиков — в идеале нужно интегрировать написание документации в процессы разработки и генерировать документы из кода. Для упрощения этих вопросов есть концепция Documentation-as-a-Code (продвигаемая сообществом [DocOps](https://t.me/docops)), которая близка технарям.
-
Обучение разработчиков писать связный текст — автогенерация не решает проблему связного, осмысленного текста, а лишь создаёт иллюзию наполнения контентом. Осмысленный текст разработчикам нужно учиться писать.
-
Сопротивление разработчиков — в первую очередь, в силу вышеописанной проблемы. Разработчикам тяжело писать осмысленный текст. Есть ощущение, что преодолеть его помогут чек-листы и формальные инструменты.
-
Структура архитектурной документации и навигация по этой документации
Пользовательская документация
Пользовательская документация понятна стороннему человеку и предназначена для онбрординга в проект/продукт.