Современный человек нередко сталкивается с документацией в том или ином ее виде: инструкция от мультиварки, схема сборки мебели из Ikea и даже приветственное обучение в новом приложении. Все это разновидности документации. Документация в широком смысле — это собранная в одном месте и структурированная информация, которая рассказывает читателю о вашем продукте.
Очевидно, что инструкция от бытового прибора и документация по ИТ-решению имеют общую цель — обучить пользователя взаимодействию с продуктом. Различаться будут объем таких документов, а также стиль изложения информации внутри них. Необходимо, чтобы содержание документов было понятно читателям и отвечало на поставленные ими вопросы. Ниже я расскажу о том, как этого добиться.
Определите аудиторию
Любая документация пишется для конкретной аудитории. Это влияет как на всю ее структуру в целом, так и на используемую в ней терминологию. Поэтому нужно понимать, для какой аудитории вы пишете. Для этого читателей можно разделить на группы по характеристикам:
- Уровень знания продукта. Если ваш продукт хорошо представлен на рынке, имеет аналоги и понятные алгоритмы взаимодействия, то не нужно описывать общеизвестные принципы. Однако, если продукт является нишевым и широко не представлен на рынке – как это, например, бывает с корпоративными инструментами, – то аудитория с большей вероятностью не имеет богатого опыта взаимодействия с подобными решениями. В данном случае стоит более подробно описывать аспекты работы с продуктом;
- Специализация. Вам нужно однозначно различать документацию для конечных пользователей и для технических специалистов, которым необходимо глубокое понимание алгоритмов работы;
- Родной язык. Весьма очевидный пункт, который тем не менее важно принять во внимание перед написанием документации: на каком языке вашу документацию будут чаще читать? Если вы пишете только для соотечественников-шотландцев, то не усложняйте себе задачу и не используйте какой-то другой язык в погоне за глобализацией.
Выберите структуру
После того, как определена аудитория, самое время выбрать способ организации статей внутри документации. Их порядок должен помогать решать задачи конкретной аудитории читателей: если это конечные пользователи, то они открывают документацию для поиска ответа на общий вопрос: “Какие действия я могу совершать на данном экране?” / “Как выполнить нужную операцию?” / "Где, в конце то концов, найти группу для любителей корги?"
Когда ваши читатели – это технические специалисты, то они будут искать ответы на более сложные вопросы по настройке или по логике работы алгоритмов вашего продукта. Поэтому каждая статья в документации должна отвечать на конкретный вопрос, заданный читателем-представителем определенной аудитории.
Такие статьи должны объединяться в группы и выстраиваться в понятном порядке: например, если это документация для конечных пользователей, то порядок следования статей можно выстроить согласно порядку следования экранов внутри вашего продукта. Если читателями будут технические специалисты, то статьи можно группировать по модулям, которые представлены внутри вашего решения.
Определите структуру и правила изложения
Документацию будет проще читать, если каждая из статей будет наследовать единую структуру и следовать общим правилам.
Структура сильно зависит от типа документации, но есть некоторые общие рекомендации:
- В начале всегда рассказывайте, о чем пойдет речь далее, и что читатель получит в итоге: узнает, как настраивать конкретную функциональность, или какие действия можно выполнить на определенном экране;
- Далее перечисляйте предусловия, если их выполнение обязательно;
- Затем изложите основную часть, из которой пользователь должен получить то, за чем пришел;
- После основной части перечислите полезные ссылки: например, на описания других связанных модулей и функциональностей.
Правила изложения тоже будут уникальными для каждой отдельной документации, но если попытаться перечислить общие рекомендации, то вот они:
- Используйте одни и те же синонимы для одних и тех же терминов, чтобы избежать ситуаций, когда в одной статье используется термин “тестовая среда”, а в другой — “безопасная среда”. Такие разногласия в терминах только запутывают и усложняют поиск. Стремитесь к согласованности и однозначности;
- Шрифты, стили, оформление текста — все это должно быть единообразно для разных типов текста во всех статьях, что поможет читателям лучше ориентироваться при чтении;
- Картинки также должны быть в единой стилистике: оформление подписей и сносок на них не должны отличаться от статьи к статье. Это поможет быстрее находить нужную информацию на картинке, не вчитываясь в каждое пояснение.
Используйте контрольную группу
Ранее мы определили, что каждая статья внутри документации должна отвечать на конкретный вопрос, который озвучен в ее начале.
“Если во время чтения документации пользователи сталкиваются со сложностями и не могут продвинуться к желаемому результату, то документация не выполняет свою основную задачу”.
Чтобы убедиться в отсутствии двусмысленностей, неточностей или неправильных ссылок в документе, лучше всего перед публикацией попросить коллег выполнить описанные в документации инструкции. Затем исправить в тексте все возникшие затруднения. Это позволит сгладить эффект замыленного взгляда и получить на выходе документ, который будет легко читаться и помогать отвечать на поставленные вопросы.
Собирайте отзывы
Документацию нужно поддерживать в актуальном состоянии. В ней могут устареть скриншоты, измениться шаги или поменяться названия кнопок, и новые читатели снова начнут испытывать сложности. Поэтому нужно наладить некий канал для сбора обратной связи, посредством которого читатели смогут указывать на проблемные места. Даже если до этого ваши коллеги без проблем выполнили все шаги инструкций, может оказаться, что те же шаги вызывают у читателей сложности.
Поэтому всегда оставляйте канал для связи с вами, чтобы оперативно получать информацию о возникших сложностях.
***
В качестве заключения хочется напомнить, что вашу документацию будут читать люди, а не роботы, со свойственными людям пороками: лень и нежелание разбираться в сложных вещах. Поэтому старайтесь писать как можно проще, избегать лишнего канцеляризма и непонятных терминов.
Нет ничего хуже документации, которая заставляет читателей чувствовать себя глупыми. Задача документации полностью противоположна и направлена на облегчение жизни пользователя. Руководствуйтесь рекомендациями, приведенными выше, и пишите документацию с заботой о вашей аудитории.
***
Об авторе
Systems Analyst и Product Owner в команде CT Software в группе компаний CT Customertimes corp — CT Customertimes, CT Consulting, Masterdata, CT Cloud.
Участвует в разработке продуктов компании в качестве Systems Analyst. Управляет пакетом CT Mobile внутри платформы Salesforce в качестве Product Owner.
Больше информации о продуктах, кейсы и истории успеха здесь:
Сайт: https://masterdata.ru/
LinkedIn: https://www.linkedin.com/company/masterdata/
Instagram: https://www.instagram.com/masterdata_cis/
Facebook: https://www.facebook.com/1masterdata