Понятная, актуальная и доступная всем заинтересованным база знаний — полезный рабочий инструмент для любой команды. Не всегда получается сделать её такой с первого раза, особенно если в компании нет выделенного человека под эту задачу.
Привет, Хабр! Меня зовут Анастасия Граф, я руковожу отделом разработки технической документации в Maxim Technology. За плечами — 16 лет преподавания математического моделирования в вузе и восемь в управлении и реинжиниринге базы знаний службы поддержки большой государственной информационной системы, разработке и внедрении методологии наполнения, актуализации, верификации базы знаний разработки, юротдела и нескольких торговых предприятий.
Контент в базе знаний не может существовать сам по себе — его нужно организовать и им нужно управлять. Именно этому я посвятила серию статей. В этой части разберёмся с универсальными требованиями к базе знаний на примере Confluence и с чего начать «уборку»: как сортировать содержания накопленных знаний, что учесть и как это может в итоге выглядеть. Статья подготовлена по мотивам доклада на Saint TeamLead Conf.
Общие требования
Есть четыре универсальных требования, применимых к любой базе знаний вне зависимости от специализации. Знаниями должно быть легко делиться, нужный материал — легко находить, статьи должны быть написаны доступным языком, а все материалы — достоверны и актуальны. Всё вышеперечисленное можно модифицировать в зависимости от специфики, болей и проблем конкретной команды. А теперь разберём эти требования подробнее.
1. Легко делиться знаниями. Когда мы просим джуна написать справку, он, скорее всего, боится сделать что-то не так. Мидлы говорят, что у них нет на это времени и они расскажут вкратце голосом: «А вы запомните, пожалуйста, и желательно не переврите».
Но такая схема не работает, очень уж она затратна. Именно по этой причине нужно создать такие условия, при которых каждый желающий сможет и захочет самостоятельно написать статью в базу знаний. Правила размещения статей должны быть понятны и просты. Сформировав культуру фиксации знаний в базе несложно перейти к формуле «Ищи ответ в базе знаний, не найдешь — приходи за консультацией. Полученный ответ зафиксируй отдельной статьёй или расширь имеющуюся».
2. Статьи написаны понятным читателю языком. Когда вы пишете материал, нужно чёткое понимание, о чём он и для кого.
Например, ответы на кадровые вопросы следует писать так, чтобы не нужно было переводить с бухгалтерского и юридического на IT-шный. Например, если срок исчисляется в рабочих днях, то тут же нужно написать, как их считать.
3. Нужный материал просто найти. С этим может помочь стажёр или вчера пришедший в команду человек. Нужно продумать, как оптимизировать поиск в используемом инструменте и дерево страниц, настроить перекрёстные ссылки и т.д. Необходимо стремиться уйти от ситуации, когда в команде или компании есть человек, который выполняет роль библиотекаря для базы знаний.
4. Все материалы достоверны и актуальны. Если пользователь открыл несколько публикаций и они оказались устаревшими, больше он в базу знаний не пойдёт.
Чтобы добиться достоверности и актуальности, нужно продумать заранее триггеры обновления статей, порядок актуализации и кто будет за это отвечать. А после — максимально автоматизировать процесс поиска материалов для актуализации по факту того, как триггер сработал.
Реинжиниринг базы знаний: с чего начать
Итак, мы решили переделать базу знаний и навести порядок. Первым делом следует оценить, есть ли в ней что-то ценное прямо сейчас. Если важного материала много, выберите самый горячий для вас или команды. Когда вы доработаете эти разделы до состояния «отлично», уверяю, к вам придут люди, которые скажут, что хотят так же.
Если в вашей команде нет людей, которые могли бы заниматься базой full-time, подойдут внутренние эксперты в каждой теме. Специалисты, которые готовы сделать хорошо, чтобы к ним больше не приходили.
Договоритесь о терминах и сформируйте глоссарий. Если этого не сделать, кто-нибудь обязательно скажет: «А я это читаю так». Хуже, если он потом ещё и сделает на своё усмотрение. В этом смысле будет полезно посмотреть Катю Лысенко — она рассказывает об архитектуре от словаря и о том, как правильно словарь формировать. В управлении знаниями это устроено аналогично.
А теперь — работаем с оставшимся. Это можно разделить на три группы:
Точно актуально. Возможно, материал требует доработки, но это точно актуальные, горячие темы.
Точно «мусор». Предположим, сегодня мы клиенты банка А, а потому данные о банке Б точно устарели — актуализировать их нет смысла.
Но это не значит, что «мусор» надо сразу удалять. Лучше завести архивную папку, сложить это туда и закрыть доступ для посторонних. Там может оказаться ценная информация, которую вы сразу не заметили.
Надо разобраться. Эта тревожная папка давит на всех и в какой-то момент должна исчезнуть из базы знаний. Для этого к ней нужно всё время возвращаться.
У нас в Maxim Technology был принцип: если страница на протяжении квартала из этой папки ни разу не использовалась, мы отправляли её в архив и квалифицировали как «мусор». Но работа с этим видом данных должна быть регулярной, а не когда есть настроение. Нужно заручиться поддержкой руководства, что на это будет уходить некоторое время.
А пока наводим порядок, у нас есть возможность параллельно проектировать. Речь идёт о решениях, которые могут меняться на ходу и к концу у вас появится какая-нибудь шестая итерация того, что вы делали.
Начинаем проектировать: триггеры обновлений, разновидности контента и триггеры
Типы контента
Первое, что мы делаем — планируем, какие типы материалов использовать. Это позволит впоследствии ими грамотно управлять и лучше искать.
У нас реализованы:
страницы глоссария включают термины, о которых договаривались выше;
страницы справочников — они отвечают на один короткий вопрос;
страницы книги — обычно состоят из набора справочников.
Сначала было три типа контента, а теперь их уже семь. Это связано с пополнением библиотеки документации и дополнительных описаний.
Триггеры обновления
Мы фиксируем их после перепроверки актуальности написанного материала. Это может быть закрытый тикет на разработку или изменение законодательства.
Например, у нас была база знаний службы поддержки со ссылками на нормативно-правовые акты. Как только документ менялся, мы проверяли пул ответов, который ссылается на этот нормативно-правовый акт.
Связи материала между собой
Вне зависимости от инструментов вы можете устанавливать эффективные связи между материалами. Одна статья дополняет другую или отвечает на дополнительные вопросы. В одном документе у нас ТЗ, в другом — бизнес-описание, и всё это должно быть связано между собой. Полезно дать возможность всем заинтересованным участникам добавлять связи по ходу работы над документом. Лучше они будут лишними, чем их не будет совсем.
Статусные модели, шаблоны верификация: что нужно проектировать на ходу
Здесь нужно сразу сделать оговорку: мы постоянно будем что-то менять, дорабатывать и улучшать.
Статусная модель страниц
Первое, что нужно спроектировать — статусную модель страниц. Она нужна, чтобы каждый понимал актуальность материала.
Мы используем набор статусов вне зависимости от типа контента. Это позволяет примирить тех, кто не хочет быть автором, но хочет хорошую документацию, с тем фактом, что часть информации пока ещё в процессе подготовки.
Наши статусы:
опубликовано — страница актуальна, можно пользоваться;
в работе — идёт работа по подготовке контента;
на согласовании — страница подготовлена, но ещё не верифицирована;
на корректировку — требуется актуализация контента;
архив — страница неактуальна и актуализация не предусмотрена.
У вас могут быть другие статусы. Их не должно быть слишком много, а суть должна быть понятна интуитивно.
Если страница имеет статус, отличный от «Опубликовано», а она нужна для решения рабочей задачи, заинтересованный может влиять на приоритет работы над ней. Если страница в архиве, но есть причина достать её оттуда и актуализировать, то и это возможно.
Кто будет владельцем контента
Нужно назначить ответственного за проверку базы знаний, когда триггер обновления контента сработает. Обычно это тимлид или выделенный менеджер из числа технических писателей или аналитиков.
Шаблоны
Чем больше материалов шаблонизировать, тем охотнее люди будут писать документы. Понятная структура снижает порог входа. Например, автор хочет создать инструкцию для второй линии поддержки. Он нажимает кнопку «Создать инструкцию для второй линии», которая переправляет его в нужную папку. Это сильно упрощает процесс. Но тут же накладывается обязательство — нужен ревьюер. К этому вопросу мы ещё вернёмся.
Мы используем Confluence. Шаблон можно создать глобально или в нужном пространстве. У нас их много, некоторые содержат внутри себя только чек-лист без структуры. Например, есть карточка сервиса с шаблоном, где по каждому поводу есть подсказка.
Он реализован таким образом, потому что отчёт по свойствам страницы в Confluence позволяет собрать из единичных страниц с табличными данными целый каталог. А в нём уже можно использовать контекстный поиск. Так мы сразу решаем несколько задач на уровне большой и сложной системы.
При этом свойство страницы — это рамочный макрос, который оборачивает всё внутри себя.
Требования по оформлению
Здесь нужны чёткие правила. Чем проще они будут сформулированы, тем лучше. Если поместить их перед чек-листом внутрь шаблона, это повышает шанс на использование — важное будет перед глазами.
Порядок верификации
Проверка материалов зависит от того, как сформирована команда и каким образом в ней работают над базой знаний.
В Maxim Technology автор отдаёт черновик на ревью, и этот процесс может проходить по-разному. В одном случае технический писатель передаёт материал коллеге, чтобы убедиться, что «проклятие знаниями» не случилось — читает тот, кто наименее погружён в тему.Этот человек правит орфографию и пунктуацию и приводит текст в соответствие с нашим стайл-гайдом. Если это техническая документация, мы обращаемся за ревью в команду разработки. Тут в ходе ревью производится верификация написанного, оценивается глубина изложения и т.д. Возможно, будет несколько итераций правок.
Если вы хотите какой-то профит, отдайте материал тому, кому это посильно, но он плохо разбирается в вопросе, но будьте готовы к двигающимся срокам.
Порядок актуализации
В нашем случае актуализация начинается с построения отчетов и бордов, соответствующих сработавшему триггеру. Так получаем список статей, нуждающихся в проверке и корректировке.
Для этого нам нужны инструменты, которые позволяют быстро фильтровать и управлять контентом. В Confluence используем отчёт «Содержимое по меткам». Главное — чтобы контент был управляемым и его можно было быстро отобрать по характеристикам и актуализировать по триггеру.
Дерево страниц
У каждого пользователя свои задачи — нельзя спроектировать дерево, которое решает сразу все. При этом можно сделать достаточно хорошую систему, а для остальных придумать способ просматривать этот контент не через дерево.
Если понадобится его перестроить, это можно сделать в течение двух-трёх часов при нормальном инструменте. Любой вопрос можно решить в следующем пункте.
Вспомогательные элементы, упрощающие поиск
Их может быть много в зависимости от инструмента — в моём случае это метки. Они заменили недоступные из-за санкций макросы и встроенные статусы с фильтрацией.
Так появилось три типа меток:
Метки-статусы — они определяют степень готовности и актуальности статьи.
Метка называется в соответствии со статусом. У каждой страницы только одна статусная метка.
Тематические метки определяют круг тем, к которым относится страница. Их количество не ограничено. Если пользователь формулирует вопрос совершенно другими словами, все ключевые слова могут стать метками — это облегчит поиск.
Технические метки позволяют собрать материалы по какому-либо признаку. Они дают возможность выстроить нужные нам фильтры с учётом нюансов.
Например, вышла доработка, которая меняет часть какого-то функционала. Сначала мы отбираем по метке всё, что относится к нему, а затем вводим метку, совпадающую с номером тикета, который закрылся и стал триггером. Эту метку мы устанавливаем в страницы, которые нужно править. Затем появляется возможность по фильтру отобрать список нуждающихся в актуализации страниц и назначить их кому-то.
Так могут выглядеть метки для конкретной страницы:
Порядок сбора обратной связи по контенту
Это последнее, что мы проектируем. Здесь люди расскажут, нуждается ли наш контент в дополнении или что привело читателей в восторг.
Но это ещё не всё. У нас всё ещё есть владелец материала, и он должен организовать работу и людей.
Запрет на copy-paste и управление контентом
Минимальные затраты обеспечиваются запретом на copy-paste — тогда не придётся выверять формулировки в десяти разных местах. Это означает, что итоговый документ будет набором справочников, выстроенным так,чтобы чтобы по нужному запросу получался связный текст.
В режиме редактирования это выглядит так:
В случае с итоговым документом мы имеем дело с тематической подборкой материалов. Собираем данные с помощью двух типов документов:
отчёт «Содержимое по меткам»;
отчёт «По свойствам страницы».
Есть глоссарий — в нём все статьи по нужной теме. Если нужно выстроить списки эффективнее, нужны метки — на них строятся оба типа отчётов.
Управление контентом
Контент не может существовать сам по себе — им нужно управлять. У меня есть рабочий стол, а в команде — технические писатели, которые занимаются исключительно документацией.Она может выглядеть таким образом:
Или если мы готовим книгу на какую-то тему, есть страницы в разных статусах.
Это всё примеры самых простых отчётов «Содержимого по меткам», которые из коробки доступны во всех других инструментах. Я пока не видела инструмента, у которого такого отчета нет.
Выводы
Контент в базе знаний не может существовать сам по себе — им нужно управлять. Это можно делать даже в том случае, если на эту задачу нет выделенной роли, люди в команде не хотят писать и база знаний в целом похожа на склад полезного и лишнего.
В этой статье разобрали:
с чего начинается «уборка» — сортировка контента на актуальный, требующий актуализации и тот, что нет смысла актуализировать;
как сортировать содержание накопленных знаний;
в каком порядке разбирать отсортированное;
систему мониторинга и управления контентом.
В следующей части, которая выйдет 26 января, мы разберёмся, зачем нужно ревью любой документации и как с его помощью повышать уровень знаний в командах. Не пропустите!
Скрытый текст
А чтобы узнать больше информации, переходите на сайт «Онтико» и следите за анонсами новых конференций — в этом году вас ждет много интересного!
