[Подкаст] Выпуск #7. Процесс разработки технической документации (разработка)
В основе любой деятельности лежит набор определенных процессов. Разработка технической документации не является исключением. В сегодняшнем выпуске о втором этапе процесса создания документации.
Слушайте подкаст на любимых платформах:
Поделитесь подкастом с друзьями и коллегами
Расшифровка выпуска
00:00 - 00:54 Приветствие
Добро пожаловать в подкаст технического коммуникатора Техкомпод!
Меня зовут Владимир Юсупов. Я - технический коммуникатор и, по совместительству, ведущий данного подкаста.
На календаре 27 апреля 2023 года.
Выпуск номер семь.
Продолжаю небольшую серию выпусков о процессе разработки технической документации.
Напомню, что процесс состоит из следующих этапов:
- Подготовка.
- Разработка.
- Согласование.
- Публикация.
00:55 - 01:14 Этап “Разработка”
В предыдущем выпуске речь шла о подготовке, а тема сегодняшнего выпуска - разработка.
Данный этап процесса разработки технической документации также можно разделить на несколько шагов (или частей):
- Структурирование.
- Написание.
- Вычитка.
Теперь рассмотрим каждый из этих шагов более подробно.
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. Я периодически пишу там заметки по техписьму и коммуникациям. И конечно же подписывайтесь на подкаст.
На этом у меня всё. До встречи через две недели!
С Вами был Владимир Юсупов. Подкаст технического коммуникатора Техкомпод.
Пока!
Оповещение о новых выпусках
Получайте оповещение о публикации новых выпусков подкаста. Никакого спама. Всего одно письмо в две недели.