Лекция 3. Документация и управление знаниями

Третья лекция — про то, что остаётся от проекта, кроме кода: знания о том, как он устроен и почему сделан именно так. Разобраны системы управления знаниями и модель SECI, источники знаний и способы их хранения, виды документации, инструменты, языки разметки и то, что хранит карточка задачи в трекере. Всё это напрямую нужно для лабы «Документирование проекта».

1. Система управления знаниями

Определение 1. Система управления знаниями (Knowledge Management System, KMS) — набор процессов и инструментов для сбора, хранения, поиска и передачи знаний внутри организации или для личного пользования.

Дополнение. Это не только программа. Вики без договорённости о том, кто и когда её обновляет, через полгода превращается в кладбище устаревших страниц. Процессы — кто пишет, где искать, как проверять актуальность — такая же часть системы, как сам инструмент.

Знания делят на два вида, и вся модель из следующего раздела построена на этом делении:

2. Цикл знаний: модель SECI

Модель SECI описывает, как знание переходит между неявной и явной формой. Название — по первым буквам четырёх переходов.

2.1. Социализация

Из неявного в неявное. Опыт передаётся от человека к человеку через совместную работу, наблюдение, подражание и наставничество. Ничего не записывается: джун сидит рядом с сеньором и перенимает, как тот читает логи.

2.2. Экстернализация

Из неявного в явное. Мысли, идеи и интуитивные навыки превращаются в понятную форму — концепции, схемы, тексты, метафоры. Нужно сформулировать то, что «просто знаешь», — поэтому этот переход даётся труднее остальных.

2.3. Комбинация

Из явного в явное. Существующие явные знания объединяются и систематизируются в новые формы: базы данных, отчёты, программы, документы. Например, из десятка разрозненных заметок собирается одно руководство.

2.4. Интернализация

Из явного в неявное. Изученная теория и документы снова превращаются в личный опыт и навыки — «обучение через действие». Прочитать инструкцию по деплою — это ещё знание; задеплоить по ней пять раз — уже навык.

3. Где искать знания

1. Официальная документация — языка, библиотеки, внутренняя документация проекта. Первое место, куда стоит смотреть.
2. Коммуникация — коллеги, чаты, созвоны. Часто быстрее всего, но ответ остаётся в голове спросившего, если его не записать.
3. Код и его история — сам код, комментарии, сообщения коммитов, обсуждения в пулл-реквестах. Отсюда и требования к гигиене коммитов из первой лекции: хорошее сообщение коммита объясняет, почему сделано изменение.
4. Задачи и баг-трекеры — история задачи хранит, зачем понадобилась функция, какие варианты обсуждали и почему отказались от остальных.

Список на лекции остался открытым: источников больше.

Дополнение. Ещё несколько мест, где ищут знания: логи и системы мониторинга (как система ведёт себя на самом деле), тесты (исполняемая спецификация: по ним видно, как код задуман работать), внешние источники — issues и обсуждения в репозиториях библиотек, Stack Overflow, доклады с конференций.

4. Как генерировать знания

1. Мозговой штурм — команда накидывает идеи без критики, потом отбирает.
2. Ретроспективы — регулярный разбор: что получилось, что нет, что меняем. В Scrum это часть ритуалов, см. вторую лекцию.
3. Парное программирование — двое за одной задачей: один пишет, второй следит и думает на шаг вперёд. Знание о коде сразу есть у двоих.
4. Технические доклады и внутренние митапы — человек готовит доклад и сам заодно упорядочивает свои знания.
5. Сообщества практик — группы людей одной специализации из разных команд (все фронтендеры компании, все тестировщики), которые обмениваются опытом.
6. Ротация — перевод людей между командами и проектами: знание расходится по компании вместе с людьми.

Этот список тоже открытый.

5. Как хранить знания

1. Вики
2. Файлы
3. Git
4. Чат
5. Бумага

Дополнение. У каждого способа своя цена:

Подход «документация как код» (docs as code) — Markdown-файлы в каталоге docs/ того же репозитория — ровно то, что требуется во второй лабе.

6. Как распространять знания

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

Дополнение. Другие каналы, которые встречаются в компаниях: онбординг-программы для новичков, наставничество, внутренние рассылки и дайджесты изменений, записи докладов, ревью кода (ревьюер узнаёт о новом коде, автор — о приёмах ревьюера).

7. Виды документации

Один и тот же продукт может требовать всех четырёх видов сразу: пользователю — справка, админу — инструкция по установке, команде заказчика — описание кода, а для госзаказа — комплект по ГОСТу.

8. Инструменты

Дополнение. В 2022 году Atlassian перестал продавать продукты в России, поэтому многие компании переехали с Confluence на отечественные аналоги или на вики, развёрнутые у себя. Для небольшого проекта часто хватает Markdown в репозитории и GitHub Pages или встроенной вики GitHub.

9. Языки разметки текста

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

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

• HTML — язык веб-страниц.
• XML / XHTML — XML для любых структурированных данных, XHTML — HTML по строгим правилам XML.
• Markdown — лёгкая разметка, которую удобно читать даже без отрисовки. Внутри Markdown-документов часто встречаются:
  • PlantUML — UML-диаграммы, описанные текстом;
  • Mermaid — диаграммы текстом, GitHub рисует их прямо в README.
• AsciiDoc — разметка для больших технических документов и книг.
• MediaWiki — разметка Википедии и других вики на движке MediaWiki.
• LaTeX — система вёрстки научных текстов и формул.

Дополнение. Один и тот же фрагмент — заголовок, жирное слово и ссылка — в разных разметках.

# Установка
 
Нужен **Python 3.12**. Подробнее — [в документации](https://docs.python.org/3/).

= Установка
 
Нужен *Python 3.12*. Подробнее — https://docs.python.org/3/[в документации].

= Установка =
 
Нужен '''Python 3.12'''. Подробнее — [https://docs.python.org/3/ в документации].

<h1>Установка</h1>
<p>Нужен <b>Python 3.12</b>. Подробнее — <a href="https://docs.python.org/3/">в документации</a>.</p>

\section{Установка}
Нужен \textbf{Python 3.12}. Подробнее — \href{https://docs.python.org/3/}{в документации}.

PlantUML и Mermaid описывают диаграмму текстом, а картинку строит программа. Так схема живёт в репозитории, меняется в том же коммите, что и код, и в истории видно, что именно поменялось. Пример на Mermaid — путь задачи по Kanban-доске:

flowchart LR
    A[Бэклог] --> B[В работе]
    B --> C[Ревью]
    C -->|замечания| B
    C --> D[Готово]

10. Системы трекинга задач

Трекер — тоже хранилище знаний: в нём видно, кто, что и когда делал. На примере Kanban карточка задачи хранит:

• ФИО ответственного;
• дедлайн;
• потраченное на задачу время;
• текст задачи.

Дополнение. В реальных трекерах (Jira, YouTrack, GitHub Issues и Projects) к этому добавляются статус (колонка доски), приоритет, метки, связи с другими задачами и ссылки на коммиты и пулл-реквесты. Если в сообщении коммита или описании пулл-реквеста на GitHub написать Closes #12, задача 12 закроется сама после слияния — и в ней останется ссылка на код, который её решил.

Частые ошибки

1. Считать KMS программой. Это процессы плюс инструменты; вики без владельцев и правил обновления устаревает.
2. Путать направления в SECI. Экстернализация — из неявного в явное (записать), интернализация — из явного в неявное (научиться делать по записанному).
3. Считать социализацию «болтовнёй». Это полноценный канал передачи неявного знания: наставничество и парная работа.
4. Хранить решения в чате. Через месяц их не найти; итог обсуждения нужно перенести в вики, задачу или репозиторий.
5. Писать одну документацию на всех. Пользователю, администратору и разработчику нужны разные документы.
6. Считать README документацией по ГОСТу. Для госзаказчика состав и форма документов жёстко заданы стандартом.
7. Путать Mermaid и PlantUML с самостоятельными языками разметки текста. Это языки описания диаграмм, которые встраивают в Markdown и другие документы.
8. Оставлять карточку задачи без ответственного и дедлайна. Тогда по доске нельзя понять, кто чем занят и что горит.

Мини-тренажёр

1. Сформулируйте, что такое система управления знаниями, и объясните, почему это не просто «купить Confluence».
2. Сеньор показывает джуну, как он отлаживает утечку памяти, а джун повторяет за ним. Какой это переход SECI?
3. Вы прочитали внутренний гайд по код-ревью и за месяц ревью он стал для вас привычкой. Какой переход?
4. Из пяти разрозненных статей вики собрали одно руководство для новичков. Какой переход?
5. Почему экстернализацию считают самым трудным переходом?
6. Назовите четыре источника знаний из лекции.
7. Чем ротация помогает распространять знания?
8. Заказчик собирается сам дорабатывать продукт после сдачи. Какой вид документации ему нужен?
9. Где сравнительно надёжнее хранить описание архитектуры проекта — в чате или в Git — и почему?
10. Перечислите четыре поля Kanban-карточки из лекции.
11. Чем Mermaid удобнее картинки, нарисованной в графическом редакторе?
12. Какой язык разметки используют для формул и научных статей?

Шпаргалка