Критерии оценки документации
Привет! Меня зовут Илья и я занимаюсь систематизацией информационных ресурсов[1]. К сожалению, многие компании этим пренебрегают, уповая на достаточную эрудицию своих сотрудников. С таким же успехом можно было бы сказать: «Делайте хорошо, плохо не делайте».
На эту статью меня вдохновили:
Конечно, в зависимости от отрасли, документацию можно и нужно оценивать по‑разному. Но на красоту также можно и нужно влиять. Отмечу, что эти размышления относятся к описаниям ИТ‑продуктов, а не к юридическим и прочим артефактам. Исключением будет только визуальная составляющая — наглядность информации is a must. Дело даже не в квалификации читателя — информации стало слишком много и она постоянно обновляется.
Итак, хорошая[2] документация выполняет 2 функции:
Экономит ресурсы сопровождения продукта или услуги. Чем лучше корпоративная база знаний, тем эффективнее решаются задачи технической поддержки и разрабатываются новые решения.
Помогает в принятии решения о покупке продукта или услуги. При прочих равных, чем понятнее описание, тем клиенту проще сделать выбор.
Исходя из этого, главным критерием для оценки статьи или документа[3] является скорость восприятия информации. То есть как быстро найти нужное или понять важное?
С точки зрения визуального и смыслового восприятия:
Структура — общее восприятие документа:
Какова область для чтения, удобен ли такой формат?
Если статья большая, то есть ли заголовки и оглавление?
Есть ли схема описанного решения, компонентов системы?
Форматирование — насколько удобно читать:
Разделен ли текст на абзацы?
Оформлены ли списки?
Оформлены ли гиперссылки?
Выделены ли
ключевые слова
?Выделена ли
важная информация
и где она расположена?Одного ли размера скриншоты и не сливаются ли с текстом?
Грамотность — кроме базовой грамматики важны смысловые и эстетические аспекты:
«В случае, если…» (избыток слов, канцелярит);
Наличие плеоназмов (дублирование смысла);
Местоимения типа «вы», «вам», «вас» с большой буквы;
Сложные предложения с избытком запятых лучше разбивать на простые;
Понятна ли причинно‑следственная связь? Где это настраивается, что должно появиться?
Актуальность информации:
Актуально ли описание данной версии?
«Оплата подписки возможна с помощью сервиса Apple Pay или Google Pay»
Полнота — нужно изучить предметную область и задаться вопросом «а все ли описано?»
Можно просто проверить последовательность шагов —, а работает ли инструкция?
А все ли методы указаны: есть «создать» и «удалить», а редактировать нельзя?
Стилистика — написан ли текст в одном стиле? В художественном или информационном?
«Вы можете обновить страницу, нажав F5.»
«Для обновления страницы необходимо нажать F5.»
«Опытный пользователь ПК знает, что для обновления страницы необходимо нажать F5.» (Я так не пишу:)
Для базы знаний:
Обнаруживаемость (Discoverability) — возможность найти статью по ключевому слову:
«Если вы поищете что‑то в огромном корпоративном Confluence на 20 тысяч страниц и получите 300 результатов на ваш поисковый запрос, то, скорее всего, вы начнете грустить. Потому что понимаете, что релевантность этих страниц непонятна, а вам нужно прочитать, как минимум, первые 2 страницы выдачи, пролистав каждый из этих документов.»
Навигация:
Понятно ли что и в каком разделе находится?
Быстро ли находится нужный раздел, за сколько кликов?
Подробное описание только в одном месте, или в каждом разделе описано по‑разному?
С технической точки зрения:
Тиражируемость:
Насколько трудоемко экспортировать исходную информацию в разные форматы?
Нужно ли сотруднику знать Git и Markdown, или WYSIWYG достаточно?
С точки зрения бизнеса:
Стоимость создания и сопровождения информационных ресурсов.
У этого критерия есть 2 составляющие:
Стоимость изготовления и поддержки актуальности материалов;
Стоимость чтения этих материалов — проще прочитать или обратиться к коллеге?
Это не только про ФОТ. Могут понадобиться изменения в процессах производства или корпоративной культуре:
Кем, как и где ведутся материалы по проекту?
Есть ли стандарты оформления проектных артефактов?
Как фиксируется опыт при управлении инцидентами?
Проводятся ли мероприятия по обмену знаниями?
Каков вообще уровень зрелости компании?
Примечания:
[1]: Под информационными ресурсами следует понимать комментарии в задачах, материалы по обучению и интервью, регламенты работы сотрудников и т. п. То есть все то, что позволяет понять продукт компании и процессы его производства.
[2]: Документация хороша тогда, когда затраты на ее производство и поддержку меньше принесенной пользы (видео: «Документация — это про деньги»).
[3]: Если неформально, то такие понятия как »документ» и »статья» можно считать синонимами. По сути, и то и другое является результатом обработки информации для последующей публикации в том или ином формате. Разница видится в том, что к статье едва ли применимы какие‑либо стандарты оформления. Как правило, она пишется в свободном стиле.