Как написать хорошую документацию (пошаговое руководство)

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

Ведь все читают документацию:

• Команды по маркетингу работают с плейбуками — своего рода маркетинговой документацией.
• Группы поддержки и технические специалисты используют руководства пользователя, руководства по установке, примечания к коду — «основную» техническую документацию.
• Другие полагаются на стандартные операционные процедуры, справочные материалы, технологические документы, контрольные списки — типичную документацию знаний компании.

Клиенты также используют ориентированную на клиента документацию, чтобы изучить решение или устранить свои проблемы самостоятельно (поддержка уровня 0).

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

Виды документации

В своем выступлении о типах документации Даниэле Прочида или Divio AG делит документацию на четыре типа:

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

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

Имея это в виду, давайте начнем с нашего руководства по написанию документации.

Определите, действительно ли вам нужно документировать это

Ваш продукт может делать сотни вещей. Там может быть еще больше способов настроить его. У вас может быть кодовая база из тысяч строк. И вы также можете генерировать МНОГО знаний в своей повседневной работе.

Но невозможно задокументировать все… и не все нужно документировать.

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

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

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

Будут ли ваши клиенты следовать вашей документации шаг за шагом, чтобы начать работу с вашим решением? Это делает вашу документацию «целенаправленной».

Или ваши разработчики будут использовать его во время работы и совместной работы над вашим следующим циклом выпуска? В этом случае вы ищете «ориентированную на понимание» документацию.

Или ваш HR-ресурс будет ссылаться на него при обработке заявок? У вас здесь «информационно-ориентированная» документация.

И поможет ли им ваша документация?

Помимо этого, вы также можете подумать о том, как ваши усилия по документированию помогут вам на более высоком уровне:

• Улучшит ли ваша документация поддержку нулевого уровня и позволит ли она вашим конечным пользователям самостоятельно решать свои проблемы (отклонение)?
• Поможет ли это вашим командам стать лучше в том, что они делают?
• Станет ли ваша команда продуктивнее?

Узнайте, когда документировать это

Общая идея состоит в том, чтобы не начинать слишком рано (или поздно).

Если вы не уверены в том, как на самом деле будет развиваться процесс или как вы собираетесь реализовать свое «видение», лучше не документировать его и подождать, пока все немного материализуется.

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

Это «гибкий» подход к документации.

Часто лучшее время для работы с определенными типами документации (такими как процедуры и процессы) — это когда вы их фактически выполняете.

Сосредоточьтесь на лучшем способе документирования

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

Честити Блэквелл из Yelp делится некоторыми разочарованиями, когда вся ваша документация не хранится в одном месте:

У вас есть документ, в котором все объясняется об этой услуге, и вы уверены, что информация, необходимая для решения этого инцидента, где-то там есть. «Вы можете попробовать найти это в вики или, может быть, в репозитории Google Docs. О, и у меня есть несколько заметок в моем домашнем каталоге, и я думаю, что некоторое время назад я видел электронное письмо об этом».

Естественно, вы не хотите, чтобы это случилось с вами. Вот почему вы должны обдуманно выбирать инструменты для документирования. Если вы ведете документацию для конечных пользователей, лучше всего использовать простую в заполнении базу знаний, такую ​​как Heroic Knowledge Base. Вы можете найти некоторые альтернативы здесь.

Если вы ведете документацию для своих команд, воспользуйтесь вики-решением, таким как WikiPress, или внутренним решением для управления знаниями Heroic Knowledge Base (да, оно работает как единое целое!). Или ознакомьтесь с некоторыми из этих вариантов решений для управления знаниями.

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

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

Решите, что написать

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

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

В зависимости от документации, которую вы создаете и для кого, вам необходимо знать, какие формы может принимать ваша документация. Джейкоб Каплан-Мосс подробно рассказывает об этом в книге «Что писать». Он объясняет, почему учебные пособия, тематические руководства и справочные материалы в большинстве случаев составляют основную часть документации:

• Учебники: Учебники или инструкции — это самая основная форма документации. Что касается нашей документации для клиентов, учебные пособия — это ресурсы с практическими рекомендациями, которые наши пользователи используют для добавления базы знаний на свой веб-сайт с помощью нашего подключаемого модуля или заполнения ее статьями.
• Тематические руководства: Тематические руководства, как правило, намного глубже, чем учебные пособия, и ориентированы на более специализированные темы. Для нас это наши руководства по таким темам, как перевод и интеграция. Мы свободно классифицируем их как продвинутые темы.
• Справка. В контексте документации, предназначенной для клиентов, этот тип содержит информацию о нашей интеграции с нашими партнерами, которая может оказаться полезной для наших пользователей при настройке интеграции. Или ссылки на любые материалы, которые могут оказаться полезными при внедрении любого из наших решений HeroThemes.

Начните с файла README (и опирайтесь на него)

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

Если вы работаете над документацией по коду, которую будут использовать ваши коллеги (разработчик/тестировщик/оптимизатор), ваш файл README будет выглядеть определенным образом.

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

Теперь просто возьмите файл READMe или план документации и заполните его по одному разделу за раз. Вот несколько ресурсов из нашего блога, которые помогут вам заполнить документацию:

• Окончательный шаблон статьи базы знаний (инфографика): мы изучили самые успешные статьи базы знаний наших клиентов и расшифровали, как выглядит хорошая статья базы знаний. Такие статьи составляют значительную часть вашей пользовательской документации, поэтому используйте эту инфографику, чтобы создавать их с рекордной скоростью.
• Как написать подробные пошаговые стандартные операционные процедуры (СОП): это краткое практическое руководство по написанию практических инструкций или стандартных операционных процедур, которые предлагают пошаговые инструкции о том, как выполнить намеченную работу — очень полезно. при создании внутренней вики компании или базы знаний.
• Что такое документация процесса? И как правильно документировать свои процессы: Еще одно краткое руководство по написанию документации по процессам, которая является неотъемлемой частью набора внутренней документации вашей компании.
• Как написать часто задаваемые вопросы и 5 простых способов написать идеальные ответы на ваши часто задаваемые вопросы: эти два поста помогут вам подготовить свои часто задаваемые вопросы в течение часа и отклонить множество предпродажных вопросов, как босс.

Когда закончите, не забудьте добавить часть обзора и тестирования.

Рецензирование — неотъемлемая часть процесса документирования. Это поможет вам убедиться, что ваша документация действительно работает. В своем пятиэтапном процессе рецензирования документации технический писатель Том Джонсон говорит, что нельзя пропустить первый этап, когда вы — автор документации — заставляете «продукт работать» для себя, следуя написанным шагам.

Установите расписание обновлений

Документация начинает устаревать, как только она опубликована. Поэтому вам нужен график обновлений.

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

Документация для разработчиков — документация по техническому коду — всегда актуальна (внутренняя документация).

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

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

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

Заворачиваем…

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

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

Вам слово… Как вы сейчас подходите к написанию документации?