Привет! Меня зовут Илья и я навожу порядок в информационных ресурсах компании.
На эту статью меня вдохновили:
Пост Артемия Лебедева «Красота профессиональных документов»
Статья Семёна Факторовича «Вам кажется, что с вашей документацией что‑то не так?»
Начальные тезисы «Docs as Code: введение в предмет»
Каждая отрасль имеет право на свои особенности, но на красоту можно и нужно влиять. Так появились Ководство, труды Максима Ильяхова, legal design и т.д. Размышления ниже относятся не только к описанию ИТ‑продуктов. Наглядность is a must, потому что информации стало слишком много и она постоянно обновляется.
Итак, хорошая документация выполняет 2 функции:
Экономит ресурсы сопровождения продукта или услуги. Чем лучше корпоративная база знаний, тем эффективнее решаются задачи технической поддержки и разрабатываются новые решения.
Помогает в принятии решения о покупке продукта или услуги. При прочих равных, чем понятнее описание, тем клиенту проще сделать выбор.
Исходя из этого, главным критерием для оценки статьи или документа является скорость восприятия информации - как быстро найти нужное или понять важное?
С точки зрения визуального и смыслового восприятия:
Структура — общее восприятие публикации:
Макет страницы и типографика;
Заголовки, оглавление и глоссарий;
Схема взаимодействия компонентов системы;
Визуальное дополнение текста - пиктограммы и инфографика;
Повествование от большего к меньшему, от общего к частному.
Форматирование — насколько удобно читать:
Разделен ли текст на абзацы?
Оформлены ли списки?
Оформлены ли гиперссылки?
Выделены ли
ключевые слова?Выделена ли важная информация и где она расположена?
Одного ли размера скриншоты и не сливаются ли с текстом?
Грамотность — оценка материала за правописание и речевое оформление:
«В случае, если...» (избыток слов, канцелярит);
«В конечном итоге» (наличие плеоназмов, дублирование смысла);
Местоимения типа «вы», «вам», «вас» с большой буквы;
Использование «заумных» терминов или размытых формулировок;
Обилие фраз с использованием страдательного залога: «Кто на ком стоял?»
Предложения с избытком запятых и сообщений, не несущих полезной информации;
Нельзя не привести пример:
— Алло, здравствуйте! Тут неподалеку, вперемешку с птичьим клекотом и ненавязчивым шепотом ветра, будто озаряя багрянцем зеленеющие волны березовой рощи, обдавая жаром словно летнее солнце в разгар знойного душного июльского лета, испуская легкую дымку подобно поднимающемуся туману от раскинувшейся глади озера на рассвете, распугивая лесных обитателей — работящих бобров, мудрых ежей и беззаботных свиристелей, догорает дом-музей Пришвина. Нет, высылать пожарных теперь уже не нужно.
Актуальность информации с точки зрения ее применимости:
Описание версии программного обеспечения;
Релевантность ссылкок на другие материалы;
Варианты оплаты услуги (Apple или Google Pay);
Полнота — описания определяется опытным путем:
Можно ли выполнить инструкцию без поиска дополнительной информации?
Нужна ли агрегация информации (сценарии использования, FAQ и т.п.)?
Учтены ли все параметры, функции, методы (CRUD, WSDL и т.п.)?
Единообразие стиля изложения, названий, tone of voice:
«Вы можете обновить страницу, нажав F5.»
«Для обновления страницы необходимо нажать F5.»
«Опытный пользователь ПК знает, что для обновления страницы необходимо нажать F5.» (Я так не пишу :)
Для базы знаний:
Обнаруживаемость (Discoverability) — возможность найти статью по ключевому слову:
«Если вы поищете что-то в огромном корпоративном Confluence на 20 тысяч страниц и получите 300 результатов на ваш поисковый запрос, то, скорее всего, вы начнете грустить. Потому что понимаете, что релевантность этих страниц непонятна, а вам нужно прочитать, как минимум, первые 2 страницы выдачи, пролистав каждый из этих документов.»
Навигация:
Понятно ли что в каком разделе находится?
Быстро ли находится нужный раздел, за сколько кликов?
Подробности в одном месте, или в каждом разделе описано по‑разному?
— Тут ещё одна проблема. У вас формат данных описан в 3 местах, и везде по-разному. Нам по какому из описаний пакет разбирать?
— О, сразу ощущается недостаток инженерного опыта. Незамутнённый оптимизм: вера в то, что если в документации написано в 3 местах по-разному - то в одном из них почему-то непременно правильно.
С технической и организационной точки зрения:
Переносимость определяет возможности экспорта в другие форматы:
Способ ведения и хранения информации: Git, Wiki или Word?
Какой формат разметки текста: HTML, markdown или WYSIWYG?
Нужно ли использовать ГОСТ 19 и 34, OpenAPI?
С точки зрения бизнеса:
Стоимость создания и сопровождения информационных ресурсов.
У этого критерия есть 2 составляющие:
Стоимость изготовления и поддержки актуальности материалов;
Стоимость чтения этих материалов — проще прочитать или обратиться к коллеге?
Это не только про ФОТ. Могут понадобиться изменения в процессах производства или корпоративной культуре:
Кем, как и где ведутся материалы по проекту?
Есть ли стандарты оформления проектных артефактов?
Как фиксируется опыт при работе с пользователями?
Проводятся ли мероприятия по обмену знаниями?
Каков вообще уровень зрелости компании?
