Хорошая документация играет решающую роль в открытом проекте. Это подтверждают как многочисленные эксперты, так и результаты проведённого GitHub исследования, в котором 93% респондентов отметили важность этой составляющей.

Очевидно, что основная сложность написания документации заключается в том, что она должна быть не только полной, но и разнообразной. Технический писатель Red Hat Роберт Кратки на сайте OpenSource.com рассказывает об одном из возможных способов решения этой проблемы.

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

  • описание возможностей продукта;
  • описание действий, необходимых для решения конкретных задач.

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

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

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

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

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

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

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

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

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

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

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

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

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