Выпуск #7. Процесс разработки технической документации (разработка)

Опубликовано 27.04.2023

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

Слушайте подкаст на любимых платформах

Поделитесь подкастом с друзьями и коллегами

---

Расшифровка выпуска

00:00 - 00:54 Приветствие

Добро пожаловать в подкаст технического коммуникатора Техкомпод!

Меня зовут Владимир Юсупов. Я - технический коммуникатор и, по совместительству, ведущий данного подкаста.

На календаре 27 апреля 2023 года.

Выпуск номер семь.

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

Напомню, что процесс состоит из следующих этапов:

1. Подготовка.
2. Разработка.
3. Согласование.
4. Публикация.

00:55 - 01:14 Этап “Разработка”

В предыдущем выпуске речь шла о подготовке, а тема сегодняшнего выпуска - разработка.

Данный этап процесса разработки технической документации также можно разделить на несколько шагов (или частей):

1. Структурирование.
2. Написание.
3. Вычитка.

Теперь рассмотрим каждый из этих шагов более подробно.

01:15 - 03:00 Структурирование

Полученная при проведении исследований информация должна быть осмыслена и чётко структурирована для дальнейшей понятной подачи целевой аудитории.

Существует несколько подходов структурирования технической документации. Наиболее логичным, на мой взгляд, является дедуктивный подход. Это означает, что материал в документации подаётся “от общего к частному”. Сначала представляется высокоуровневая информация для общего понимания, а затем происходит углубление в детали.

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

Думаю, суть понятна. Результатом выполнения текущего шага должно стать оглавление будущего документа, а инструментом создания структуры и оглавления являются заголовки.

Необходимо всегда держать в голове мысль о том, что люди читают документацию в поисках ответов. Они хотят понять, как сделать что-то или что может произойти, если они чего-то наоборот не сделают. И эти знания читатели хотят получить быстро. Поэтому обязательно со всей серьёзностью подходите к структурированию документации. Это позволит читателям быстро найти нужную информацию.

03:01 - 05:31 Написание

К этому моменту проведены все изыскательные работы, собрана и структурирована необходимая информация.

Как Вы помните, помимо предметных исследований были упомянуты оформительские исследования. Самое время применить эти знания при написании документации.

Кстати, стоит заметить, что существуют два подхода в решении данного вопроса:

• сначала сформировать документ полностью (текст, таблицы, графические изображения и т.д.), затем приступать к оформлению;
• оформлять документацию в соответствии с требованиями в процессе написания.

Мне по душе второй вариант. Но это дело личных предпочтений. Главное, чтобы был достигнут нужный результат. Оформление документации подробнее будет рассмотрено в следующем выпуске.

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

Если сроки позволяют, забудьте хотя бы на день о только что написанном документе и вернитесь к нему немного погодя со свежим взглядом. Это позволит более качественно провести заключительную проверку документа перед отправкой на согласование. Если же сроки “горят”, то хотя бы на час-другой переключитесь на другие задачи, прогуляйтесь или просто выпейте чаю. “Экспресс-вариант” будет не таким эффективным, но всё же окажет позитивное влияние.

Упомяну также несколько слов о стиле изложения.

Бытует мнение, что документация должна быть написана простым и доступным языком. Кто-то подсчитывает количество слов в предложениях, букв в словах и т.д. Моё мнение такое: длина предложений безусловно важна, но более важно то, что материал должен быть представлен не на простом, а на понятном для целевой аудитории языке. Кстати, язык этот может быть далеко не самым понятным для представителей другой аудитории. Здесь необходимо учитывать различные термины, профессиональный жаргон и много других нюансов.

Как только закончена работа над первой версией, приходит черёд вычитки.

05:32 - 10:08 Вычитка

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

Вычитка должна включать в себя логическую и грамматическую проверки.

Под логической проверкой понимается корректное (логически правильное) описание последовательных действий. Например, сначала должно быть приведено описание процесса формирования отчёта в аналитической системе, а уже затем варианты сохранения и выгрузки данных. И никак иначе. Также графические изображения должны логически совпадать с текстовым материалом.

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

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

Более того, вычитка должна быть двухфакторной. Первая стадия вычитки выполняется самим автором документа (причём, как минимум, дважды и при этом вслух), а вторая - наблюдателем.

Наблюдателем может стать коллега. Важно здесь то, чтобы кто-то помимо автора прочитал документ.

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

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

Структура реестра может различаться. Приведу один из вариантов перечня столбцов реестра.

Структура реестра замечаний

№ п/п	Столбец	Пояснение
1	№ п/п	Номер замечания по порядку
2	Объект замечания	Наименование документа
3	Версия объекта	Версия документа
4	Дата замечания	Дата выдачи замечания функциональным экспертом
5	Автор замечания	Фамилия Имя (Отчество) функционального эксперта
6	Замечание	Формулировка (текст) замечания
7	Комментарий исполнителя	Ответ технического писателя на замечание функционального эксперта по результатам отработки замечания
8	Статус исполнителя	Статус отработки замечания техническим писателем (например, Выполнено / Отклонено / В работе / Снято автором и т.д.)
9	Дата статуса исполнителя	Дата отработки замечания техническим писателем
10	Исполнитель	Фамилия Имя (Отчество) технического писателя
11	Статус автора	Статус подтверждения отработки замечания после проверки автором (например, Принято / Отклонено)
12	Дата статуса автора	Дата подтверждения отработки замечания автором
13	Комментарий автора	Комментарий функционального эксперта к ответу технического писателя при отработке замечания (например, по мнению автора замечание устранено не полностью)

10:09 - 10:26 Результат этапа “Разработка”

В итоге результат выполнения этапа “Разработка” следующий:

• подготовлена первая версия документа (или документов) в соответствии с разработанной структурой;
• подготовлен шаблон реестра замечаний (для отработки возможных замечаний функциональных экспертов на этапе согласования).

10:27 - 11:14 Заключение

На этом заканчиваю сегодняшнюю тему.

Спасибо, что прослушали этот выпуск от начала до конца. Если у Вас возникли вопросы, замечания или предложения, пишите мне. Заходите на мой сайт techwritex.ru. Я периодически пишу там заметки по техписьму и коммуникациям. И конечно же подписывайтесь на подкаст.

На этом у меня всё. До встречи через две недели!

С Вами был Владимир Юсупов. Подкаст технического коммуникатора Техкомпод.

Пока!