#DevOpsConf Анастасия Граф. Как организовать базу знаний так, чтобы даже новичок-джун всё смог найти сам? Анастасия - из Maxim Technology, разработка для Taxi Maxim, 350 ИТ-шников распределенная команда по городам России. Доклад развивает тему доклада на #TeamleadConf-2023 (есть конспект в моем отчете), но отличается фокусировка. Тогда был рассказ о процессе и технических способах организовать документацию, а здесь фокус на результат - базу знаний с легким поиском и с соучастием разработчиков в ее поддержке. И основная задача тут - изменение культуры: переход от ситуации, когда тот к кому нужна информации, обращается в чатик или к соседу, к ситуации, когда человек сначала идет за ответом в базу знаний, и только если ответ не нашел идет его искать к соседу или в чатик, а найдя ответ - еще и дополняет базу знаний. Это именно изменение культуры. Но чтобы оно произошло должны быть предпосылки.

4 требования, они были сформулированы на слайде, а потом по каждому шел рассказ.

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

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

2) Статья написана понятно читателю. Целевая аудитория часто шире, чем задумываешься. Есть люди, далекие от ИТ, которым тоже интересно не ходить с вопросами к ИТ. И здесь - ревью, обратная связь и легкость изменения. Перевести реакцию из "у вас непонятно" к "мне непонятно это и это".

3) Легко найти нужный материал. Тут есть проблема со сленгом - надо писать понятные названия. А еще работать с метками. У них документацию ведут сами команды, и они образуют дерево статей так как им удобно, в своей логике и ориентируются в своем пространстве. Которая отличается от логике соседней команды. А поиск нужен по всей документации, и метки помогают определить нужный набор страниц. И они помогают делать тематические подборки, на которых собирается вся необходимая информация.

4) Все материалы достоверны и актуальны на текущую дату. Самое сложно реализуемое. Что не надо перепроверять, а если нашел неверное - то заинтересован исправить. Реализуется за счет статусной модели для страниц, и за счет активного применения сборных страниц, которое позволяет править в одном месте. Статус - метка на странице: В работе, Ревью, Опубликована, На корректировку.

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

На этом - все. А мне во время доклада пришла мысль посмотреть на изменение культуры документирования как на процесс уборки и поддержания порядка: (1) есть пространства, где ты при необходимости убираешься сам, (2) есть - где активно сигнализируешь о беспорядке, (3) есть - где лишь жалуешься и страдаешь, а (4) есть - где игнорируешь. И задача - чтобы расширить пространства 1 и 2 каждого членов команды, обеспечив перекрыте всего пространства активистами. Это может дать другой взгляд.