Техническая документация (далее — ТД) показывает, как использовать программный продукт, описывает его функции и фиксирует важные детали его разработки.
И если в ТД будет всего одна ошибка, пользователь начнёт проверять каждую реплику — особенно при описании API и архитектуры. В итоге документ потеряет эффективность.
Чтобы такого не случилось ни в документации к играм, ни к корпоративным ПО стоит пройти несколько шагов.
Проведите исследование
Анализ — это стартовая точка в создании любой технической документации. Он начинается с изучения:
- Цели. Подумайте, чем документ будет полезен пользователям.
- Текущей технической документации. Уточните актуальность имеющихся данных. Если большая часть устарела, документ лучше писать с нуля.
- Аудитории. Определите, кто ваш читатель — члены команды, эксперты, широкая публика и т. д. Например, рядовых пользователей отпугнёт обилие терминов, а IT-специалистов напряжёт блок для новичков.
- Документации в других сервисах. Посмотрите на Stripe, Exolve, 2ГИС, Superjob и так далее. Референсы всегда помогают понять, как это можно реализовать на практике.
Например, мануал ниже рассчитан на массового читателя — в нём нет сложных формулировок, зато достаточно много подробных скриншотов.
А здесь у 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.
Только после объективного и, главное, успешного тестирования техдокументация считается завершённой и внедряется в работу с целевыми пользователями.
Заключение
Разработка технической документации — это сложный и многоэтапный процесс. Он требует тщательного анализа, правильного подбора инструментов и детального тестирования.
Только в этом случае ТД сможет привлечь пользовательское внимание к продукту и оптимизировать внутренние процессы компании.
