Техническая документация: с чего начать?
Говорят, что для идеального продукта не нужна документация. И так понятно, как его установить, настроить и начать пользоваться. Однако едва ли найдется программа без справочных материалов. Разработчики хотят, чтобы клиенты могли осваивать новые инструменты самостоятельно, без помощи технической поддержки. Если вы планируете писать документацию для своего продукта, обратите внимание на несколько ключевых моментов.
Формат
Чтобы создать полезную документацию, недостаточно просто структурировать данные, важно представить их в удобной для пользователей форме. В промышленности, например, по-прежнему востребованы печатные инструкции. Производители шкафов управления оборудования размещают схемы разводки в специальных отсеках на дверцах. Благодаря этому инженеры могут работать со схемами, не имея под рукой ноутбука.
Один из самых популярных форматов для программных продуктов — это online help, или интерактивная справка. Такая документация доступна с любых устройств и индексируется поисковыми системами. Индексация превращает информационный портал в дополнительное средство привлечения пользователей, то есть online help становится полноценным инструментом маркетинга и играет роль в продвижении продукта на рынке. Через поисковые системы проходит 90% трафика в сети, и игнорировать это — значит упускать аудиторию. Основная задача портала с документацией — ответить на вопросы клиентов, помочь настроить продукт, научить им эффективно пользоваться. Второстепенная — заявить о продукте и привлечь потенциальных клиентов.
Продукт определяет формат документации. Проанализируйте, кто и в каких условиях будет ее читать, и выбирайте формат исходя из удобства пользователей.
Инструменты
Если продукт определяет формат документации, то формат определяет подходящие инструменты. Ситуация схожа с написанием кода: иногда подойдет простейший текстовый редактор, а иногда не обойтись без продвинутой IDE. Чтобы рассказать о небольшой утилите, хватит и одного Readme файла. Для комплексных решений могут понадобиться инструкциии с внутренним поиском, использованием шаблонов для однотипных страниц и экспортом в несколько форматов. В таких случаях используют программы для создания инструкций, или help authoring tools (HAT). Они помогают техническим писателям работать с текстами благодаря поддержке совместного редактирования, продвинутому функционалу для экспорта, подготовке материалов для печатных форматов и так далее.
Подбирайте ПО для создания документации в соответствии с особенностями продукта. Не усложняйте.
Команда и процессы
Некоторые организации нанимают технических писателей в штат, а кто-то передает документирование на аутсорс. В любом случае, необходимо наладить рабочие процессы, ведь качество справочных материалов во многом зависит от готовности участников проекта делиться информацией.
Важно донести до команды идею о том, что документация существует не просто так. Она нужна пользователям, ее читают, чтобы найти ответы на вопросы о продукте. Поэтому, когда разработчик добавляет новый функционал, об этом должен знать и писатель. В компаниях, работающих по agile-методологии, о нововведениях команда узнает из регулярных совещаний. Если таких обсуждений нет, наладьте процесс передачи знаний внутри коллектива. Вариантов может быть много, но цель одна — технические писатели должны быть в курсе всего, что происходит с продуктом. Только в этом случае документация будет отображать текущее состояние продукта и будет полезна читателям.
Технические писатели должны знать о всех изменениях в продукте.
Чтобы техническая документация была полезной, нужно подумать о пользователях. Какая информация им понадобится в первую очередь? Какой формат будет удобен? Ответьте на эти вопросы и вы поймете, какие инструменты вам понадобятся. Помните, что главная задача документации — сделать информацию доступной для клиентов.
