В статье я хочу рассказать об одной очень интересной теории разработки документации на системы и программы. Её авторы утверждают, что создали ни много ни мало «Великую Единую Теорию Документации» (The Grand Unified Theory of Documentation). Мы привыкли с опаской относиться к заявлениям о том, что кто-то обнаружил сокровенную истину и раскрыл её профессиональному сообществу. В теории изложены идеи и правила, которые мы встречаем в разных методиках разработки документации и сами применяем на практике.

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

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

Авторы «Великой единой теории документации» предлагают выделить четыре основных элемента в документации на программы и системы. Эти элементы по-разному описывают один и тот же объект и порождают знание и понимание у читателя и пользователя.

Единая теория документации подробно изложена на сайте https://documentation.divio.com. Секрет хорошей документации заключается в том, что не существует единого объекта, называемого «документация». На самом деле она состоит из документов разного типа. У каждого есть свои задачи, свой формат, своя аудитория.

Четыре типа документов

Итак, не существует единой и неделимой документации. Согласно теории, она состоит из документов четырёх типов:

• Tutorials — учебник.

• How-to guides — руководство.

• Reference — справочник.

• Explanation — объяснение.

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

1. Учебник

• Помогает читателю изучить систему.

• Позволяет новичку начать работу с системой.

• Основная форма: урок.

• Аналогия: учим маленького ребёнка азам кулинарного искусства.

Учебник — это документ, который помогает превратить ученика-читателя в пользователя системы. Документы-учебники обычно самые объёмные в пакете документации. При этом писать их непросто, ведь они должны быть простыми для понимания, содержательными и при этом тщательно выверенными и надёжными.

Рекомендации:

• Позвольте пользователю обучаться на практике. Учебник должен быть ориентирован на выполнение упражнений. Упражнения должны охватывать широкий набор инструментов и операций — от простых к сложным.

• Помогите пользователю начать работать. Начните с описания простейших практик использования системы. Действия новичка могут отличаться от действий опытного пользователя. Учебник для начинающих — это не описание лучших практик работы с системой.

• Убедитесь, что уроки работают. Одна из задач учебника — вселить в новичка уверенность: в программном обеспечении, в учебном пособии, в авторе и, конечно же, в его собственных способностях достичь целей. Этому способствуют дружелюбный тон, понятный язык, логическая структура изложения материала. Но самое главное — всё, что описано в документе, должно работать. Причём работать именно так, как изложено в тексте. Если описанные в учебнике действия приводят к ошибке или неожиданным результатам, то обучение не удалось.

• Предусмотрите наглядные результаты всех действий пользователя. Все действия ученика должны приводить к понятным результатам, даже если они будут незначительными. Не заставляйте читателя проделывать множество странных и непонятных действий, прежде чем он получит какой-то видимый результат. Эффект каждого действия должен быть наглядным, очевидным и достаточно быстрым. Связь результата с выполненными действиями должна быть очевидной.

• Обеспечьте повторяемость всех уроков. Все описанные в руководстве результаты действий должны быть надёжно воспроизводимыми. Добиться этого непросто: читатели могут пользоваться разными операционными системами и инструментами, у них может быть разный уровень начальных знаний и опыта. Сама описываемая система может меняться со временем. Учебное пособие должно работать для всех и всегда.

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

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

• Сосредоточьтесь только на тех шагах, которые должен предпринять пользователь. Содержание учебника должно быть сосредоточено на поставленной задаче. Не отвлекайтесь на другие варианты выполнения действий или опциональные возможности настройки приложения. Всё это не имеет значения: прямо сейчас вашему ученику не нужно знать об этом, чтобы добиться успеха.

2. Руководство

• Ориентировано на выполнение задач.

• Показывает пользователям, как решить конкретную задачу.

• Основная форма: пошаговые описания действий.

• Аналогия: рецепт в кулинарной книге.

Руководство знакомит читателя с шагами, необходимыми для решения реальной рабочей задачи. Оно отличается от учебника тем, что ориентировано на читателей с базовым опытом работы с системой. Руководство даёт ответ на вопрос, который может сформулировать только пользователь с некоторым опытом.

Рекомендации:

• Описывайте конкретные шаги, приводящие к цели. Практическое руководство должно содержать список шагов, которые пользователь должен выполнить для решения поставленной задачи. В этом типе документа можно опустить описание элементарных действий, например, открытия файла. В руководстве не обязательно добиваться безусловной повторяемости результатов, как в учебнике.

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

• Описывайте способ решения конкретной задачи. Руководство должно отвечать на вопрос «Как мне...?» Читатель руководства знает, чего он хочет достичь, но пока не знает как.

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

• Не стремитесь к полноте любой ценой. Удобство руководства важнее, чем его полнота. В руководстве не обязательно должна содержаться полная и исчерпывающая теоретическая и практическая информация о предмете описания. Раздутое руководство не только не поможет пользователю, но и затруднит поиск нужного решения.

• Используйте описание вопроса пользователя в названии разделов. Название раздела или документа с практическими рекомендациями должно точно сообщать пользователю, ответ на какой вопрос в нём описан. «Как создать представление на основе классов» — хорошее название. «Создание представления на основе классов» и «Представления на основе классов» — плохие названия для раздела документа типа «Руководство».

3. Справочник

• Ориентирован на получение справочной информации.

• Описывает механизм работы системы и её частей.

• Основная форма: техническое описание.

• Аналогия: справочная статья в энциклопедии.

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

Рекомендации:

• Опирайтесь на исходный код системы. Используйте в справочной документации ту же структуру, что и в исходном коде или архитектуре системы или её части. Пользователю это поможет увидеть однозначную связь между объектами системы и разделами документа. Автору документа это поможет быстро выявить разделы, которые отсутствуют или нуждаются в обновлении.

• Соблюдайте строгую последовательность. Излагайте информацию единообразно и с соблюдением строгой последовательности — как в энциклопедии или словаре.

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

• Будьте предельно точны. Содержание справочника должно быть точным и постоянно обновляться. Любое несоответствие между объектом описания и текстом справочника неизбежно введёт пользователя в заблуждение.

4. Объяснение

• Ориентировано на понимание.

• Разъясняет сложные алгоритмы и процессы.

• Основная форма: аналитическое объяснение.

• Аналогия: статья об истории кулинарии.

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

Рекомендации:

• Укажите контекст. При объяснении какого-либо вопроса, опишите его предысторию и контекст, в котором он находится. Расскажите о логике проектных решений, изложите исторические причины, перечислите технические ограничения.

• Приведите альтернативы. Объяснение может содержать описание нескольких альтернативных подходов к одному и тому же вопросу. Также можно привести и проанализировать противоположные мнения.

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

Почему это важно

Разделение документов по типам позволяет получить чёткие ответы на вопросы:

• для автора — как написать? что написать? куда написать?

• для читателя — где почитать? когда почитать?

Квадранты с типами документов всё время стремятся объединиться:

• учебник и руководство описывают цепочки практических шагов;

• руководство и справочник содержат информацию, которая необходима в повседневной работе;

• справочник и объяснение содержат теоретические знания о системе;

• учебник и объяснение полезны для начального и глубокого изучения системы.

Трудно сопротивляться этому естественному притяжению типов документов друг к другу, но мы должны быть твёрдыми и непреклонными.

Подход, изложенный в теории, можно применять не только при разработке документации, но и, например, при проектировании баз знаний. Ведь то, что в теории названо «документами», не обязательно должно быть документом в классическом смысле. Это может быть любая единица информации. Например, страница или раздел. Главное, чтобы этой единице была присвоена одна (и только одна!) из четырёх меток типа: «учебник», «руководство», «справочник» или «объяснение». Это своего рода маяки в огромном море информации — они помогут не только нашим читателям, но и нам самим. Ведь это чёткие однозначные ориентиры для структурирования и организации информации.

Платон писал, что прежде чем творить космос, нужно сначала обособить и упорядочить четыре стихии. Только после этого их можно будет соединить в единое гармоничное целое.