Команда > Авторские публикации > 2015 год > Как люди используют документацию, и как эффективнее ее писать

Как люди используют документацию, и как эффективнее ее писать

Есть нескольк хорошо  известных факторов, влияющих на эффективность документации как средства обучения и как руководства по выполнению работы.

Подход к документации, известный как минимализм, проверен годами, но остается не очень известным за пределами узкого круга заинтересованных специалистов. Этот метод позволяет создавать безупречную документацию, которую легко читать. Весьма вероятно, что руководства и инструкции, созданные с применением этого подхода, будут полезны, а значит, будут использоваться.

 

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

Люди используют разные инструменты в соответствии с необходимостью достичь определенной цели. Использование документации — это почти всегда очень активный процесс. Люди обращаются к документации, когда им нужно что-то сделать прямо сейчас. Сбор информации, приобретение знаний и понимание механизмов выполнения процессов для многих читателей являются второстепенными вопросами.

Когда люди ищут в документации конкретную инструкцию «Как делать» и не могут ее найти, вряд ли они будут читать связанные с ней объяснения. Поэтому документация должна удовлетворять первостепенные потребности пользователя, иначе возможности удовлетворить второстепенные уже не будет.

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

Документация должна выполнять две функции:

  • Процедурную, объясняющую как это сделать;
  • Описательную, объясняющую, почему то или иное действие выполняется именно так.

Эти две функции являются взаимоисключающими, и поэтому материалы следует разделять, чтобы читатель мог получить именно ту информацию, которая ему нужна.

 

Как люди читают документацию?

Первое, что нужно понять: люди часто обращаются к документации в последнюю очередь. Это связано с убежденностью читателя в следующем:

  • В документации нет ничего нового, что стоило бы знать;
  • Есть более быстрые способы получить информацию;
  • Лучше спросить того, кто знает.

Документацию читают, чтобы выполнить какую-либо задачу, и у читателя есть определенные ожидания. Было доказано, что люди пытаются объединить в одно целое изучаемое и уже известное, и этот процесс замедляет чтение. Дети не имеют такого укоренившегося опыта, как взрослые, и поэтому пассивно принимают систему и следуют инструкциям, как есть. Такая разница в подходе привела к убеждению, что если вам нужно решить вопрос, привлеките к этому ребенка.

Когда люди читают документацию и пытаются научиться чему-либо, они рассуждают в процессе работы и закрепляют полученные соображения в первоначальном знании. Таким образом, люди читают документацию и руководства так же, как изучают систему — исследуя.

 

Как люди ищут информацию в документах?

Исследование показывает, что только в 25 % случаев для поиска информации использовались соответствующие  индексы и оглавления. Однако в 90 % случаев люди предпочитают бегло просматривать страницы в поисках информации.

Это частично объясняет, почему онлайн-документация и справки вызывают у пользователей такие сложности.

 

Проблемы с документацией

Руководства часто содержат обширные объяснения с узкоспециализированными примерами и практическими заданиями. Такая структура не отвечает потребности читателя в первостепенной информации. Если читатель строго следует документации, то устранение несущественных ошибок в работе программы может отнять у него много времени. Большинство документов не затрагивает вопрос устранения незначительных ошибок, а это важно для начинающего пользователя, так как часто читатель не понимает, какие его действия привели к ошибке. Руководства пользователя часто содержат слишком много материала, в котором сложно найти требуемую информацию.

 

Минимализм в документации

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

1. Не содержит:

  • повторы;
  • информацию, не относящуюся к конкретной задаче.

2. Содержит:

  • краткое изложение;
  • описание;
  • практические примеры.

Поскольку люди в целом и новички в частности не читают всю документацию, возможно, лучше пощадить их и описывать только важные характеристики и особенности.

 

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

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

 

Заголовки

Наименования заголовков должны быть ориентированы на задачу, а содержание должно являться просто указателем. Содержание должно быть сгруппировано так, чтобы было понятно новичку.

 

Удалите повторы

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

 

Оригинал статьи: http://www.technicalcommunicationcenter.com/2010/02/13/how-people-use-documentation-and-how-to-write-it-more-effectively/ (How People Use Documentation and How to Write it More Effectively)

 

Перевод с английского: ведущий консультант Doссо Анна Пономарева