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

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

Давайте рассмотрим распространенные ошибки, которые можно допустить при создании документации.

Распространенные ошибки

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

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

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

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

Как написать хорошую документацию?

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

Рекомендации по написанию документации:

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

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

Получайте обратную связь от сообщества: так вы сразу узнаете, какие руководства работают, а какие требуют доработки.

Отслеживайте изменения. Наличие системы контроля версий поможет отслеживать изменения с течением времени — в случае, если впоследствии новая функция будет удалена из-за реакции пользователей, вы сможете вернуться к предыдущей документации.

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

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

На какую аудиторию следует ориентироваться?

Текст следует адаптировать в соответствии с потребностями аудитории. Можно выделить две целевые аудитории с их разными потребностями — разработчики и пользователи.

Разработчики

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

• Документация по API: служит справочником по всему, что касается вызовов API.

• Read Me's: представляет собой обзор продукта, обычно с исходным кодом.

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

• Примечания к релизу (Release notes): содержит информацию о релизах, багфиксах и последней версии.

Пользователи

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

• Практическое руководство (How-to guide): в них пользователь проходит через пошаговый подробный процесс, помогающий ему достичь цели. Ориентировано на решение проблем. Оно помогает пользователю выполнить задачу.

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

• Объяснения: пишутся для того, чтобы помочь пользователям прояснить некоторые темы, в которых они могут не разбираться.

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

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

Заключительные мысли

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

Спасибо за прочтение!

Статья подготовлена в преддверии старта курса по DevRel. В рамках курса в ближайшее время пройдут несколько открытых уроков: по созданию IT-сообщества, запуску амбассадорской программы и определению KPI DevRel-ов.

Записаться на них можно на странице курса или по ссылкам выше.