Критерии оценки документации

Привет! Меня зовут Илья и я занимаюсь систематизацией информационных ресурсов^[1]. К сожалению, многие компании этим пренебрегают, уповая на достаточную эрудицию своих сотрудников. С таким же успехом можно было бы сказать: «Делайте хорошо, плохо не делайте».

На эту статью меня вдохновили:

• Пост Артемия Лебедева «Красота профессиональных документов»

• Статья Семёна Факторовича «Вам кажется, что с вашей документацией что‑то не так? Вам не кажется»

• Начальные тезисы «Docs as Code: введение в предмет»

Конечно, в зависимости от отрасли, документацию можно и нужно оценивать по‑разному. Но на красоту также можно и нужно влиять. Отмечу, что эти размышления относятся к описаниям ИТ‑продуктов, а не к юридическим и прочим артефактам. Исключением будет только визуальная составляющая — наглядность информации is a must. Дело даже не в квалификации читателя — информации стало слишком много и она постоянно обновляется.

Итак, хорошая^[2] документация выполняет 2 функции:

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

• Помогает в принятии решения о покупке продукта или услуги. При прочих равных, чем понятнее описание, тем клиенту проще сделать выбор.

Исходя из этого, главным критерием для оценки статьи или документа^[3] является скорость восприятия информации. То есть как быстро найти нужное или понять важное?

С точки зрения визуального и смыслового восприятия:

1. Структура — общее восприятие документа:

• Какова область для чтения, удобен ли такой формат?

• Если статья большая, то есть ли заголовки и оглавление?

• Есть ли схема описанного решения, компонентов системы?

2. Форматирование — насколько удобно читать:

• Разделен ли текст на абзацы?

• Оформлены ли списки?

• Оформлены ли гиперссылки?

• Выделены ли ключевые слова?

• Выделена ли важная информация и где она расположена?

• Одного ли размера скриншоты и не сливаются ли с текстом?

3. Грамотность — кроме базовой грамматики важны смысловые и эстетические аспекты:

• «В случае, если…» (избыток слов, канцелярит);

• Наличие плеоназмов (дублирование смысла);

• Местоимения типа «вы», «вам», «вас» с большой буквы;

• Сложные предложения с избытком запятых лучше разбивать на простые;

• Понятна ли причинно‑следственная связь? Где это настраивается, что должно появиться?

4. Актуальность информации:

• Актуально ли описание данной версии?

• «Оплата подписки возможна с помощью сервиса Apple Pay или Google Pay»

5. Полнота — нужно изучить предметную область и задаться вопросом «а все ли описано?»

• Можно просто проверить последовательность шагов — а работает ли инструкция?

• А все ли методы указаны: есть «создать» и «удалить», а редактировать нельзя?

6. Стилистика — написан ли текст в одном стиле? В художественном или информационном?

• «Вы можете обновить страницу, нажав F5.»

• «Для обновления страницы необходимо нажать F5.»

• «Опытный пользователь ПК знает, что для обновления страницы необходимо нажать F5.» (Я так не пишу:)

Для базы знаний:

7. Обнаруживаемость (Discoverability) — возможность найти статью по ключевому слову:

«Если вы поищете что‑то в огромном корпоративном Confluence на 20 тысяч страниц и получите 300 результатов на ваш поисковый запрос, то, скорее всего, вы начнете грустить. Потому что понимаете, что релевантность этих страниц непонятна, а вам нужно прочитать, как минимум, первые 2 страницы выдачи, пролистав каждый из этих документов.»

8. Навигация:

• Понятно ли что и в каком разделе находится?

• Быстро ли находится нужный раздел, за сколько кликов?

• Подробное описание только в одном месте, или в каждом разделе описано по‑разному?

С технической точки зрения:

9. Тиражируемость:

• Насколько трудоемко экспортировать исходную информацию в разные форматы?

• Нужно ли сотруднику знать Git и Markdown, или WYSIWYG достаточно?

С точки зрения бизнеса:

10. Стоимость создания и сопровождения информационных ресурсов.

У этого критерия есть 2 составляющие:

1. Стоимость изготовления и поддержки актуальности материалов;

2. Стоимость чтения этих материалов — проще прочитать или обратиться к коллеге?

Это не только про ФОТ. Могут понадобиться изменения в процессах производства или корпоративной культуре:

• Кем, как и где ведутся материалы по проекту?

• Есть ли стандарты оформления проектных артефактов?

• Как фиксируется опыт при управлении инцидентами?

• Проводятся ли мероприятия по обмену знаниями?

• Каков вообще уровень зрелости компании?

Примечания:

• [1]: Под информационными ресурсами следует понимать комментарии в задачах, материалы по обучению и интервью, регламенты работы сотрудников и т. п. То есть все то, что позволяет понять продукт компании и процессы его производства.

• [2]: Документация хороша тогда, когда затраты на ее производство и поддержку меньше принесенной пользы (видео: «Документация — это про деньги»).

• [3]: Если неформально, то такие понятия как «документ» и «статья» можно считать синонимами. По сути, и то и другое является результатом обработки информации для последующей публикации в том или ином формате. Разница видится в том, что к статье едва ли применимы какие‑либо стандарты оформления. Как правило, она пишется в свободном стиле.