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

Фиксация знаний / Документация

Управление знаниями в IT часто путают с более узкой темой фиксации знаний.

К практикам фиксации знаний можно отнести:

  • Регистрацию фактов, например:

    • фиксация договорённостей в момент, когда они случились

    • фиксация информации о новых проектах, когда по этим проектам началась работа

    • фиксация информации о задачах, когда эти задачи впервые сформулированы

    • фиксация информации о новых элементах инфраструктуры в тот момент, когда они создаются

  • Написание документации, например:

    • по проектам

    • по архитектуре

    • для конечных пользователей

Огромным препятствием на пути фиксации знаний является отсутствие навыков формулирования своих мыслей у сотрудников. И с этим вызовом можно бороться двумя путями:

  • Упрощать процесс входа в фиксацию знаний

  • Обучением и развитием нужных навыков

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

Практики фиксации знаний

С фиксацией знаний есть три фундаментальные проблемы:

  1. Никто не пишет документацию/не фиксирует знаний

  2. Никто не читает зафиксированное

  3. Никто не обновляет зафиксированное

Подавляющее большинство компаний не продвигается дальше пункта 2, что приводит команды к состоянию "У нас есть вики, но там всё жутко устаревшее и никто ей не пользуется".

Для того, чтобы фиксация знаний заработала — крайне важно, чтобы этот процесс был встроен в другие процессы. То есть процесс не должен иметь возможности продолжиться, если знание не зафиксировано. Например:

  • Если вы хотите документацию по задачам — то документирование должно стать частью definition of done ваших задач, т.к. задача не может считаться законченной, пока с не готова документация по задаче. И, как следствие, новые задачи не должны браться в работу, пока не закончены старые. Подробнее - см. "Регистрация фактов".

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

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

  • Знания можно фиксировать прямо в том месте, где идёт работа. Комментарии в коде и git-коммиты — это тоже инструменты для фиксации знаний. Подробнее - см. "Регистрация фактов".

Регистрация фактов, "цифровые следы"

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

К регистрации фактов может относится, например: фиксация задач в таск-трекерах (Jira, Redmine, YouTrack и др.), фиксация доступов и паролей к сервисам и серверам, фиксация договорённостей (афтермитинги, CRM-системы и др.).

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

Например, при внесении изменений в системе контроля версий (git, tfs, ...) указывать связь этих изменений с задачей, в которой есть связь с бизнес-причинами, побудившими эту задачу, и автором. Это позволит открыв код понять, зачем написана каждая строчка и можно ли её менять в дальнейшем.

Написание документации

Под написанием документации мы подразумеваем, что пишется структурированый текст, с аккуратными, понятными формулировками, возможно — с доп. контентом в виде схем/скриншотов/примерами исходных кодов.

Написание подобных текстов — долгий, дорогостоящий процесс, требующий навыков. Поэтому вдвойне важно делать контент, который будет востребован и развивать у сотрудников навыки чтения контента. Также важно корректно встроить написание документации в процессы: документация, написанная до реализации/в отрыве от реализации, имеет не очень высокую ценность.

Документацию можно писать

  • Силами инженеров/разработчиков — сложно, потому что у них есть другие заботы и вообще они не умеют, нужно помочь им сформировать навыки написания и модификации контента.

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

Обратите внимание, что под словом "документация" может скрываться как минимум три явления:

  • Отчётная документация — использующаяся для тендеров и контрактов и, как правило, имеющая мало связи с реальностью и нуждами

  • Архитектурная документация / аналитическая документация — не понятная не-профессионалу и предназначенная для того, чтобы помочь узким специалистам, работающим с системой (например, архитекторам или аналитикам) упомнить всё. В такую документацию нужно отдельно и долго онбордить людей.

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

Проблемы и измерение эффективности

Фиксация знаний помогает:

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

  • Вникать в незнакомые части проекта

  • Саппорту, отладке

  • Проектированию и принятию решений

  • Онбордингу конечных пользователей продуктов

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

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

При внедрении практик фиксации знаний, knowledge manager-ы сталкиваются последовально с тремя проблемами:

  • Никто не делает записей

  • Никто не читает сделанных записей

  • Записи устарели / ошибочны, об этом знают, но не исправляют

Фиксация

  • Вложения в фиксацию знаний должны окупаться, нужно найти баланс между гибкостью и документированностью

  • Людей нужно приучить в нужный момент заниматься фиксацией

  • Людей нужно научить правильно делать записи (у примеру, ммногие боятся заниматься документированием, так как не умеют писать тексты)

Чтение

  • Нужно научить людей в нужный момент читать записанное

  • Нужно сделать так, чтобы люди знали, как в нужный момент найти записанное

Исправление

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

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

Вот ряд проблем:

  • Устаревание информации

  • Дублирование информации

  • Не понятно, куда и как вклинить свои правки

  • Не понятно, как проводить рефакторинг зафиксированных документов

  • Нет реальных ответственных за документы

Подходы и решения

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

В докладе Trello — эффективная система управления знаниями для небольшой IT-команды (конспект) Роман Хорин рассказывает о внедрении trello в качестве системы управления знаниями "на минималках". Он подходит для небольших компаний и заставляет задуматься - а нужны ли сложные, дорогостоящие системы.

Управление знаниями: какие документы нужны и что в них фиксировать — Максим Цепков делает обзор возможных документов при работе над проектом, разбирает целесообразность использования каждого из них и погружается в исторические причины появления тех или иных подходов к фиксации знаний о проектах. Ознакомившись с этим докладом вы лучше сможете сформулировать из чего должна состоять ваша проектная документация.

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