Содержание статьи:
- Задачи технической документации
- Участники процесса
- Создание документации в организации: жизненный цикл
- Автоматизация процесса работы с технической документацией
- Документерра – один из лучших сервисов для работы с документацией
Ни одна качественная база данных технической документации не появляется самостоятельно в ходе работы над продуктом или сервисом. Она всегда становится результатом длительного и напряженного труда – и не только технического писателя, но всей команды. На пути к идеалу, конечно, встречается немало испытаний, но коллективное понимание рабочего процесса и использование правильных стратегий и инструментов помогают их преодолевать.
Основные пункты, обязательные для работы с любой документацией, включают в себя планирование, сбор информации, собственно написание и публикацию. Однако было бы некорректным сказать, что этим все и ограничивается: а как же проведения ревью? Согласования? Корректировки? Или, в конце концов, дальнейшее сопровождение и поддержание базы знаний в актуальном состоянии? Давайте более внимательно разберем жизненный цикл технической документации.
Задачи технической документации
Итак, в первую очередь, приступая к выполнению любого таска, и по написанию документации в том числе, необходимо определиться с основной задачей, которую вы планируете решить.
В процессе разработки технической документации мы можем так или иначе охватить следующие процессы.
Во-первых, мы буквально организуем обмен знаниями и их контроль. Проработанная база знаний, особенно дополненная функцией тестирования сотрудников, представляет собой очень мощный инструмент управления корпоративным образованием, обеспечивает оперативный онбординг новичков и снижает риски потери информации в случае увольнения сотрудников.
Во-вторых, база данных технической документации – это один из лучших каналов для обеспечения коммуникации между отделами. Главное, поддерживать ее в максимально актуальном состоянии с полноценной информацией обо всех аспектах разработки и эксплуатации вашего продукта. Тогда все участники рабочего процесса смогут быть в курсе планов, требований, ожидаемого результата и так далее, что позволит избежать разночтений и обеспечит более плавное и точное достижение финальных целей. Также это ощутимо экономит ресурсы команды: когда большинство вопросов можно решить самостоятельно обращением к надежному источнику проверенной информации, высвобождается большое количество времени и сил, которые можно потратить не на ожидание ответа от коллеги, например, а на реализацию задач. Самый простой пример здесь – снижение нагрузки на сотрудников техподдержки при наличии полной и грамотно структурированной пользовательской справки или инструкции с хорошей системой поиска. Прямым следствием этого становятся растущая удовлетворенность пользователей в целом и возможность специалистов более качественно, внимательно и быстро решать сложные кейсы и оказывать услуги.
В-третьих, наличие единой базы знаний помогает управлять качеством продукта и решает вопросы стандартизации и единообразия. Готовые шаблоны, регистрации, сертификат безопасности, установленные стандарты (ГОСТ), сертификация, паспорт, история предыдущих сложных кейсов и принятых по ним решений облегчают рабочие процессы в настоящем и закладывают надежный фундамент для будущего, снижая затраты ресурсов и вероятность повторения негативных сценариев.
Участники процесса
Независимо от цели, с которой вы создаете тот или иной технический документ, рабочий процесс не фокусируется на одном только техписателе. Как мы говорили не раз, создание документации в организации – результат командной работы. Кто же может входить в число специалистов, необходимых для разработки базы знаний?
- SME, или эксперты в предметной области, то есть специалисты, обладающие наиболее полными знаниями и экспертизой по тому или иному вопросу, продукту, профессиональной сфере. Они могут дать качественную консультацию, прояснить сложные специфические моменты, проверить результат работы технического писателя.
- Разработчики продукта. С их помощью можно убедиться в том, что технические аспекты документации, относящейся к коду или, например, функционалу продукта, соответствуют действительности, или разработать качественную систему обучения для быстрого вовлечения новых специалистов в процесс разработки.
- Менеджеры проекта. Их задача – контролировать рабочие процессы, координировать команду и отслеживать соблюдение сроков.
- Дизайнеры продукта. Так как они работают над изучением и проектированием пользовательского взаимодействия с продуктом, они могут представить немало полезной информации, которую крайне важно задокументировать на будущее.
- Технические писатели. Собственно, те самые профессионалы, которые работают в тесном тандеме с перечисленными выше специалистами, чтобы база данных технической документации была качественной, надежной, полезной и даже стильной.
Однако, над каким бы типом технической документации вы ни работали, какую бы позицию в команде ни занимали, вам необходимо обладать пониманием всего процесса от начала до конца.
Создание документации в организации: жизненный цикл
Итак, любой проект должен пройти определенные ступени развития от идеи до реализации. Документация чего-либо – не исключение. Например, нам нужно написать технологическую инструкцию для промышленного сектора – нормативный документ, описывающий последовательность процедур, методов и приемов технологического производства. Эта инструкция является частью конструкторской документации и может быть самостоятельным документом или приложением к техническим условиям для производства определенной продукции. Как же будет выглядеть ее жизненный цикл?
- Планирование. Определите задачу инструкции, способы оценки достижения этой задачи, ее целевую аудиторию, сроки реализации, какие специалисты должны принять участие в процессе. Ответьте на вопросы: зачем именно этот документ нужен именно этой аудитории и вашему продукту?
- Исследование. Изучите всю доступную информацию, проведите необходимые интервью, уточните детали у экспертов, протестируйте продукцию или его отдельную функцию самостоятельно.
- Черновик. Соберите черновую версию документа, проработайте визуальную составляющую, структуру, формат.
- Рецензирование. Передайте документ на проверку экспертами или иными ответственными лицами, получите их заключение и проработайте правки.
- Редактура. Приведите документ в соответствие с корпоративными стандартами и регламентом, вычитайте текст на предмет различных недоразумений, рисков неправильного толкования, трудночитаемых фраз и т.д., а также проверьте форматирование и оформление.
- Согласование. Передайте результат на проверку и одобрение.
- Публикация. Разместите документ в необходимом формате, доступном конечному пользователю.
- Поддержка. Отслеживайте взаимодействие пользователей с документом, вносите правки по необходимости. Все изменения в продукте, затрагивающие информацию в опубликованном документе, должны быть своевременно внесены.
Ниже представлен пример технической документации от GitHub:
Впрочем, в зависимости от продукта, команды, задачи конкретного документа количество шагов может меняться: что-то может повторяться, что-то – выпадать. Тем не менее, как можно заметить, процесс разработки технической документации не ограничивается непосредственно написанием текста и добавлением визуалов. Он представляет собой достаточно обширную и планомерную работу с вовлечением различных специалистов и не останавливается на публикации, а требует постоянного мониторинга в дальнейшем.
Только так можно создать качественную и надежную документацию, будь это пользовательская справка, руководство, внутренняя база знаний, спецификации на оборудование или что-либо еще.
Автоматизация процесса работы с технической документацией
Сегодня среди многих специалистов разных сфер формируется тренд на оптимизацию рабочих процессов с помощью различных сервисов и подходов. Техническое писательство – не исключение, поэтому здесь можно отметить стремление к автоматизации, активной работе с шаблонами, формированию строгих процессов, соблюдаемых всеми участниками. Как следствие, становятся популярными определенные подходы к разработке документации.
- Технология единого источника (single-sourcing). Неоспоримые плюсы этого подхода – в возможности создать единое хранилище контента и в дальнейшем использовать этот материал повторно в самых разных документах, сокращая количество ресурса, требуемого для разработки документации в ином случае. Также это значительно облегчает процесс поддержки готовых документов: если нужно внести какие-то изменения, вам не требуется править каждый док отдельно, достаточно поработать с общим источником в хранилище.
- Doc-as-code. Этот подход предлагает использование инструментов разработчика для написания технической документации. С помощью легковесного языка разметки вроде Markdown удобно размечать документ, для чтения подойдет абсолютно любой текстовый редактор, а хранение материалов в системе контроля версий типа Git помогает оперативно и надежно отслеживать рабочие процессы и вносить изменения.
- Собственно, автоматизация. То есть, стремление максимально сократить время на выполнение рутины, например, за счет возможности разово настроить стили и шаблоны документов. Таким образом вам не нужно каждый раз настраивать форматирование каждого отдельного документа или элемента в нем, можно сосредоточиться непосредственно на контенте.
- Использование визуальных и интерактивных элементов. Удобный чат-бот или красивая инфографика вместо полотна текста – отличный способ повысить качество взаимодействия пользователя с вашей базой знаний.
- Совместная работа. Этот подход подразумевает возможность непосредственного участия различных специалистов в работе над документацией. То есть, например, разработчик может сделать черновое описание грядущего апдейта, а технический писатель – в том же документе привести контент в соответствие со стандартами документации.
Чаще всего, конечно, компании пользуются комбинацией из нескольких наиболее удобных подходов, выбирая лучшее от каждого и формируя собственный уникальный рабочий процесс. А современный рынок программного обеспечения предлагает немало продуктов под самые разные запросы заказчика.
Документерра – один из лучших сервисов для работы с документацией
Более 10 лет профессионального опыта позволили команде Документерры разработать сильный и качественный продукт для удобной работы с технической документацией.
В соответствии с современными запросами со стороны пользователей мы создали визуальный редактор с широкими возможностями форматирования документа:
- любые таблицы, визуальные элементы, примеры кода;
- раскрываемые блоки, всплывающие надписи;
- использование как собственных шрифтов, так и сторонних;
- редактирование контента в режиме HTML-кода;
- вставка якорных ссылок и многое другое.
Также в Документерре можно создать систему шаблонов, которые в дальнейшем будет удобно применять, экономя время: просто выберите источник для копирования в начале работы с новым документом.
Технология единого источника позволяет избегать дублирования материалов за счет повторного использования контента, а удобный процесс командной работы облегчает координацию работы над документацией. В едином пространстве вы можете вести как внутреннюю, так и внешнюю документацию, назначая задачи необходимым специалистам и отслеживая процесс с помощью системы уведомлений и контроля версий.
Хотите узнать больше о преимуществах Документерры? Оставьте заявку на бесплатное демо, и наши специалисты все расскажут!
