В статье рассматриваются следующие основные вопросы:

  1. Каких целей достигает хорошо написанный документ?
  2. Что позволяет считать документ хорошим?
  3. Как составить хороший документ?

Каких целей достигает хорошо написанный документ?

В качестве основных целей составления технического документа можно выделить:

  • Обучение конечных пользователей и сотрудников продукту компании.
  • Формирование справочных материалов и баз знаний по продукту компании.
  • Снижение нагрузки на техническую поддержку.
  • Достижение рекламных целей в области продвижения сайта и продукта компании.

Что позволяет считать документацию правильной?

Ключевыми критериями, позволяющими понять, что документация написана хорошо, являются:

 

  • Находимость (findability) документации – критерий, определяющий то, насколько удобно пользователю осуществлять поиск информации, в соответствии с теорией информационного фуражирования.
  • Понятность (understandability) документации – критерий, определяющий, насколько легко пользователь может усвоить описанный в документе материал. Сможет ли он без труда воспроизвести предложенную последовательность действий, будь то установка программного обеспечения или настройка сложных модулей системы.

    Документ не должен быть перегружен как тяжелыми речевыми оборотами, так и иллюстрациями. В идеальном варианте можно ограничиться минимально необходимым количеством иллюстраций (скриншотов), для однозначного понимания сути описываемых процессов, снабдив их кратким, но исчерпывающим описанием.

  • Описание сценариев использования (use case) – ещё один немаловажный критерий хорошего технического документа. Помимо описания интерфейса и функций, пользователь сэкономит огромное количество времени, имея на руках готовые примеры использования продукта при различных сценариях.
  • Самодостаточность (self-sufficiency) документации – данный критерий является интерпретацией принципа EPPO (“Every page is page one”), согласно которому, каждая страница документации в Интернете должна быть самодостаточной и вмещать в себе всю необходимую информацию или ссылки на неё.

    Следуя данному принципу, нужно либо объединить несколько процедур, требующихся для описания определенного сценария, в один раздел, либо сделать несколько разделов, связав их ссылками.

  • Достоверность (reliability) документации – критерий, оценивающий документацию по степени отражения того, как выглядит и работает продукт прямо сейчас. Иными словами можно назвать данный критерий «актуальность документации».
  • Направленность документации на целевую аудиторию – критерий, определяющий, насколько содержание документации соответствует уровню знаний пользователей и возможности понять изложенный в ней материал.
  • Помощь в принятии решения (decision support) – критерий, согласно которому, документация должна обеспечить принятие пользователем решения, в случае возникновения затруднений в процессе воспроизведения того или иного сценария.

Как составить хороший документ?

Универсального ответа на данный вопрос нет, однако можно придерживаться несколькими правилами, которые помогут не наделать ошибок при проектировании технической документации.
  • Интересное изложение материала. В данном случае работает правило: чем более написанный текст интересен его автору, тем более он будет интересен читателю.
  • Четкое понимание конечного результата использования технического документа. Прежде чем приступать к написанию непосредственно документации, необходимо однозначно определить, какие действия ожидаются от читателя, после прочтения документации.
  • Документ должен содержать четко сформированную структуру.
  • Исключить неоднозначные местоимения.
  • Обязательное снабжение всех иллюстраций кратким описанием, со сквозной или пораздельной нумерацией.
  • Для сложных понятий и концепций необходимо обязательно подобрать логическую иллюстрацию и пример.
  • Быть готовым вносить изменения в созданный документ на основе отзыва рецензента (рецензентов) и в процессе развития описываемого продукта.

Получить консультацию по документам

Оставьте заявку на обратный звонок или свяжитесь с нами:

Позвонить
Написать
Telegram

Нажимая кнопку «Отправить», вы соглашаетесь с нашей Политикой конфиденциальности