Запросить демо
Запросить демо

От планирования до публикации: разбираем процесс разработки технической документации

18.08.2023

Содержание статьи:

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

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

Задачи технической документации

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

В процессе разработки технической документации мы можем так или иначе охватить следующие процессы. 

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

Во-вторых, база данных технической документации – это один из лучших каналов для обеспечения коммуникации между отделами. Главное, поддерживать ее в максимально актуальном состоянии с полноценной информацией обо всех аспектах разработки и эксплуатации вашего продукта. Тогда все участники рабочего процесса смогут быть в курсе планов, требований, ожидаемого результата и так далее, что позволит избежать разночтений и обеспечит более плавное и точное достижение финальных целей. Также это ощутимо экономит ресурсы команды: когда большинство вопросов можно решить самостоятельно обращением к надежному источнику проверенной информации, высвобождается большое количество времени и сил, которые можно потратить не на ожидание ответа от коллеги, например, а на реализацию задач. Самый простой пример здесь – снижение нагрузки на сотрудников техподдержки при наличии полной и грамотно структурированной пользовательской справки или инструкции с хорошей системой поиска. Прямым следствием этого становятся растущая удовлетворенность пользователей в целом и возможность специалистов более качественно, внимательно и быстро решать сложные кейсы и оказывать услуги.

В-третьих, наличие единой базы знаний помогает управлять качеством продукта и решает вопросы стандартизации и единообразия. Готовые шаблоны, регистрации, сертификат безопасности, установленные стандарты (ГОСТ), сертификация, паспорт, история предыдущих сложных кейсов и принятых по ним решений облегчают рабочие процессы в настоящем и закладывают надежный фундамент для будущего, снижая затраты ресурсов и вероятность повторения негативных сценариев. 

Участники процесса

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

  • SME, или эксперты в предметной области, то есть специалисты, обладающие наиболее полными знаниями и экспертизой по тому или иному вопросу, продукту, профессиональной сфере. Они могут дать качественную консультацию, прояснить сложные специфические моменты, проверить результат работы технического писателя.
  • Разработчики продукта. С их помощью можно убедиться в том, что технические аспекты документации, относящейся к коду или, например, функционалу продукта, соответствуют действительности, или разработать качественную систему обучения для быстрого вовлечения новых специалистов в процесс разработки. 
  • Менеджеры проекта. Их задача – контролировать рабочие процессы, координировать команду и отслеживать соблюдение сроков. 
  • Дизайнеры продукта. Так как они работают над изучением и проектированием пользовательского взаимодействия с продуктом, они могут представить немало полезной информации, которую крайне важно задокументировать на будущее. 
  • Технические писатели. Собственно, те самые профессионалы, которые работают в тесном тандеме с перечисленными выше специалистами, чтобы база данных технической документации была качественной, надежной, полезной и даже стильной. 

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

Создание документации в организации: жизненный цикл

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

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

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

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

Автоматизация процесса работы с технической документацией

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

  • Технология единого источника (single-sourcing). Неоспоримые плюсы этого подхода – в возможности создать единое хранилище контента и в дальнейшем использовать этот материал повторно в самых разных документах, сокращая количество ресурса, требуемого для разработки документации в ином случае. Также это значительно облегчает процесс поддержки готовых документов: если нужно внести какие-то изменения, вам не требуется править каждый док отдельно, достаточно поработать с общим источником в хранилище.
  • Doc-as-code. Этот подход предлагает использование инструментов разработчика для написания технической документации. С помощью легковесного языка разметки вроде Markdown удобно размечать документ, для чтения подойдет абсолютно любой текстовый редактор, а хранение материалов в системе контроля версий типа Git помогает оперативно и надежно отслеживать рабочие процессы и вносить изменения. 
  • Собственно, автоматизация. То есть, стремление максимально сократить время на выполнение рутины, например, за счет возможности разово настроить стили и шаблоны документов. Таким образом вам не нужно каждый раз настраивать форматирование каждого отдельного документа или элемента в нем, можно сосредоточиться непосредственно на контенте.
  • Использование визуальных и интерактивных элементов. Удобный чат-бот или красивая инфографика вместо полотна текста – отличный способ повысить качество взаимодействия пользователя с вашей базой знаний.
  • Совместная работа. Этот подход подразумевает возможность непосредственного участия различных специалистов в работе над документацией. То есть, например, разработчик может сделать черновое описание грядущего апдейта, а технический писатель – в том же документе привести контент в соответствие со стандартами документации. 

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

Документерра – один из лучших сервисов для работы с документацией

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

В соответствии с современными запросами со стороны пользователей мы создали визуальный редактор с широкими возможностями форматирования документа: 

  • любые таблицы, визуальные элементы, примеры кода;
  • раскрываемые блоки, всплывающие надписи;
  • использование как собственных шрифтов, так и сторонних;
  • редактирование контента в режиме HTML-кода;
  • вставка якорных ссылок и многое другое. 

Также в Документерре можно создать систему шаблонов, которые в дальнейшем будет удобно применять, экономя время: просто выберите источник для копирования в начале работы с новым документом.

Система шаблонов в Документерре

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

Хотите узнать больше о преимуществах Документерры? Оставьте заявку на бесплатное демо, и наши специалисты все расскажут! 

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