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

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

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

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

Анализ — это стартовая точка в создании любой технической документации. Он начинается с изучения:

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

А здесь у Nexweave уклон идёт на шаблоны кода, поскольку документация по API в основном пишется под IT-группу.

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

Каждая ТД уникальна и составляется с учётом целей компании и интересов аудитории. Но даже в этом случае «скелет» документации часто включает в себя такие элементы:

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

Первое, что предлагает техдокументация ChartHop, — раздел «Знакомство с сервисом», где можно узнать о навигации по сайту, порядке создания отчётов, функциях организационной диаграммы и так далее. А уже за вводным пунктом идут расширенные блоки для более узкой аудитории — разработчиков, администраторов и менеджеров.

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

При этом кроме общей структуры ТД желательно планировать содержание каждой её страницы. Вот как это сделали в Stripe:

В каждом блоке документации есть описание, метод применения, пример кода и параметры. Это не только упрощает восприятие информации читателем, но и облегчает создание новых разделов ТД из-за наличия готового шаблона.

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

Ещё в 2008 году гений юзабилити Якоб Нильсен заметил, что большинство пользователей не дочитывают и 20% страницы. В этом есть логика, ведь объёмные и бесструктурные тексты перегружают пользователей и отбивают весь интерес к чтению.

В Google предложили своё решение этой проблемы и разработали методику по оформлению техдокументации. Ниже несколько советов из этого курса.

Не частите с прилагательными и наречиями

В них мало конкретики, и они делают текст более «размытым».

Плохой пример: компилятор Explorer 2.2 намного быстрее прошлой версии.

Хороший пример: компилятор Explorer 2.2 быстрее прошлой версии на 127%.

Начинайте пункты списка с повелительных глаголов

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

Пример:

Добавляйте таблицы

Таблицы отлично отражают показатели и упрощают восприятие цифр. Чтобы таблица легче читалась:

Один абзац — одна мысль

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

Раскрывайте абзац полностью

Текст должен показать читателю:

Используйте активный голос

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

Плохой пример. Код был проанализирован специалистами.

Хороший пример. Специалисты проанализировали код.

И главное, не перегружайте пользователей текстом — пишите кратко, информативно и разбавляйте документ скриншотами.

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

По статистике, 24% брендов получили немедленную отдачу от автоматического тестирования, а ещё 44% IT-компаний перевели половину тестовых процессов в автоматический режим.

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

Веб-аналитика

Показывает:

Для этого можно использовать «Яндекс Метрику», Google Analytics, Roistat и прочие сервисы.

Интервью и опросы

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

Для этого необходимо разместить инструмент обратной связи в каждом разделе техдокументации. Здесь пригодятся сервисы, вроде: Testograf, Survey Monkey, Google Forms, Examinare и так далее.

UX-тестирование

Далеко не все пользователи захотят пройти опрос — согласно исследованиям, на это пойдут только 5–30% B2C-клиентов. С тестированием таких проблем нет.

По словам уже упомянутого Якоба Нильсена, чтобы получить эффективную статистику по ТД, достаточно привлечь 5 участников, представляющих разные типы пользователей: разработчиков, новичков, опытных юзеров и т. д. (всё зависит от формата документации). В комплексе они сложат детальную картину юзабилити вашей ТД.

Если речь идёт о технической документации по API — можно привлечь внештатного программиста или использовать онлайн-сервисы вроде Sphinx.

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

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

Только в этом случае ТД сможет привлечь пользовательское внимание к продукту и оптимизировать внутренние процессы компании.