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