Рабочий процесс технического писателя. Разработка
После выполнения шага “Подготовка” осуществляется переход к разработке документации.
Разработка так же может быть разделена на более детальные шаги:
- Структурирование.
- Написание.
- Вычитка.
Структурирование
Полученная при проведении исследований информация должна быть осмыслена техническим писателем и чётко структурирована для дальнейшей понятной подачи целевой аудитории.
Существует несколько подходов структурирования технической документации.
Наиболее логичным, на мой взгляд, является дедуктивный подход (или как я называю его в шутку - “метод Шерлока”). Это означает, что материал в документации подаётся “от общего к частному”. Сначала представляется высокоуровневая информация для общего понимания, а затем происходит углубление в детали.
Если представить пример инструкции по сверке показателей (какого-то процесса). Скорее всего, каждый показатель будет обладать определённым набором атрибутов (наименованием, формулой расчёта, другими более мелкими (базовыми) показателями и т.д.)
Так вот, вначале инструкции пользователю приводится эта общая информация и на каком-то демонстрационном примере показывается расчёт “целевого” показателя. Далее, допустим, показываются и рассказываются алгоритмы расчёта и проверки уже базовых показателей.
В этом случае структура документа (основная часть предположительной инструкции по сверке) могла бы иметь следующий вид:
1. Целевые показатели предприятия
1.1. Целевой показатель №1
1.1.1. Формула расчёта
1.1.2. Базовые показатели
1.1.3. Пример проверки
1.2. Целевой показатель №2
1.2.1. Формула расчёта
1.2.2. Базовые показатели
1.2.3. Пример проверки
1.N. Целевой показатель №N
1.N.1. Формула расчёта
1.N.2. Базовые показатели
1.N.3. Пример проверки
2. Базовые показатели предприятия
2.1. Базовый показатель №1
2.1.1. Алгоритм формирования
2.1.2. Пример проверки
2.2. Базовый показатель №2
2.2.1. Алгоритм формирования
2.2.2. Пример проверки
2.N. Базовый показатель №N
2.N.1. Алгоритм формирования
2.N.2. Пример проверки
Думаю, суть здесь понятна.
Результатом выполнения текущего этапа должно стать оглавление будущего документа, а инструментом создания структуры и оглавления являются заголовки.
Необходимо всегда держать в голове мысль о том, что люди читают документацию в поисках ответов. Они хотят понять, как сделать что-то или что может произойти, если они чего-то наоборот не сделают. И эти знания читатели хотят получить быстро. Поэтому документ должен быть чётко структурирован.
Написание
К этому моменту уже проведены все изыскательные работы, собрана и структурирована необходимая информация. Пора вспомнить второе слово в названии профессии, достать перо, чернила и стопку чистых листов бумаги. Здесь сказка начинается…
К сожалению, в этом самом месте у многих (по большей части начинающих конечно) технических писателей случается классический приступ страха белого листа.
Вроде бы всё готово к работе, но нет понимания с чего начать. Только и остаётся, что смотреть на мигающих курсор в мониторе.
Я не зря упомянул, что эта проблема характерна для начинающих специалистов. Опытные техписатели не испытывают никакой боязни перед началом написания документации. Наоборот, азарт только увеличивается. И дело здесь не столько в “сединах” и многолетних тренировках в клацаньи по клавиатуре, сколько в качестве проведённой ранее работы.
Основной причиной возникновение “ступора” является недостаточная исследовательская подготовка. Ведь к этому моменту техписатель так глубоко должен был погрузиться в объект документирования, что может практически на равных общаться с функциональными экспертами. Если этого не произошло и лист так и остаётся белым, то необходимо как можно скорее возвращаться к предыдущему этапу.
Имея же проработанную структуру документа и огромный запас информации о продукте (объекте документирования), никогда не будет возникать подобной боязни и прочих страхов. Пальцы сами будут печатать.
В предыдущей заметке было отмечено, что помимо предметных исследований есть оформительские исследования. На текущем шаге самое время применить эти знания при написании документации.
Кстати, стоит заметить, что существуют два подхода в решении данного вопроса:
-
сначала сформировать документацию полностью (текст, таблицы, графические изображения и т.д.), затем приступать к форматированию и оформлению;
-
оформлять документацию в соответствии с требованиями в процессе написания.
Мне по душе второй вариант. Но это дело личных предпочтений. Здесь главное - достигнуть нужный результат.
Итак, рано или поздно (а лучше конечно в соответствии с контрольными точками плана) будет подготовлена первая версия разрабатываемого документа.
Время отдохнуть и отложить дела в сторону, в прямом смысле.
Если сроки позволяют, лучше забыть хотя бы на день о написанном документе и вернуться к нему немного погодя со свежим взглядом. Это позволит более качественно провести заключительную проверку документации перед отправкой на согласование.
Если же сроки “горят”, то хотя бы на час-другой следует переключиться на другие задачи, прогуляться или просто выпить чаю. “Экспресс-вариант” будет не таким эффективным, но всё же окажет позитивное влияние.
Упомяну также несколько слов о стиле изложения.
Многие технические писатели утверждают, что документация должна быть написана простым и доступным языком. И здесь понеслась душа в рай… Кто-то начинает подсчёт слов в предложениях, букв в словах и т.д.
Моё мнение такое: длина предложений безусловно важна, но более важно то, что материал должен быть представлен на понятном для целевой аудитории языке. И язык этот может быть далеко не самым понятным для представителей другой аудитории. Здесь необходимо учитывать различные термины, профессиональный жаргон и множество других нюансов.
Как только закончена работа над первой версией, приходит черёд вычитки.
Вычитка
Вычиткой называется тщательная проверка разработанного документа перед отправкой на согласование функциональным экспертам и другим заинтересованным лицам.
Вычитка должна включать в себя логическую и лингвистическую проверки.
Под логической проверкой понимается корректное (логически правильное) описание последовательных действий. Например, сначала должно быть приведено описание процесса формирования отчёта в аналитической системе, а уже затем варианты сохранения и выгрузки данных. И никак иначе. Также графические изображения должны логически совпадать с текстовым материалом.
Лингвистическая же проверка подразумевает под собой поиск и исправление возможных грамматических, синтаксических, пунктуационных ошибок.
Как ни странно, вычиткой очень часто пренебрегают.
И грешат этим не только разработчики, у которых постоянно нет времени на “писанину”, и аналитики, которые тоже не горят желанием готовить эксплуатационную документацию, но и многие технические писатели не проводят должную проверку.
Причин тому может быть множество. Например, задание на разработку документации получено поздно и времени к очередному релизу хватает только на само написание документа; возникло пересечение с другими важными задачами и т.д.
Более того, вычитка должна быть двухфакторной.
Первая стадия вычитки выполняется самим автором документа (причём, как минимум, дважды и при этом вслух), а вторая - наблюдателем.
Наблюдателем может стать коллега, друг, мама, папа, сестра, брат… В общем, не столь важно, кто это. Хотя не совсем так конечно. Разумеется, всё должно быть в рамках соглашения о неразглашении конфиденциальной информации или Non-disclosure agreement (NDA).
Смысл в том, чтобы кто-то помимо автора прочитал документ. Конечно лучше всего попросить о вычитке коллегу-техписателя. Он точно знает что и как нужно делать.
Если такая возможность отсутствует, то следует обратиться за помощью к другим членам команды - к QA-инженерам/тестировщикам или, на худой конец, разработчикам. Но тут кроется опасность.
Дело в том, что все эти ребята (разработчики, тестировщики) очень хорошо знают продукт, над которым работают. Они не будут уделять должного внимания всем деталям, описанным в документации. Для них всё кажется очевидным. Но если всё-таки документация предназначается для разработчиков, то такой вариант вполне приемлем.
В случае с документацией для простых пользователей (“нетехнарей”), наиболее подходящим вариантом будет попросить ознакомиться с документом человека из компании, не имеющего отношения к объекту документации. Возможно, все потенциальные лингвистические ошибки не отыщутся, но логические очень даже можно выловить.
Для перехода к следующему шагу процесса (Согласование) необходимо подготовить рабочий документ Реестр замечаний.
После получения ответов для систематизации поступающей информации все замечания и предложения экспертов вносятся в упомянутый реестр.
Структура его может различаться. Но один из вариантов может быть следующим:
№ п/п | Столбец | Пояснение |
---|---|---|
1 | № п/п | Номер замечания по порядку |
2 | Объект замечания | Наименование документа |
3 | Версия объекта | Версия документа |
4 | Дата замечания | Дата выдачи замечания функциональным экспертом |
5 | Автор замечания | Фамилия Имя (Отчество) функционального эксперта |
6 | Замечание | Формулировка (текст) замечания |
7 | Комментарий исполнителя | Ответ технического писателя на замечание функционального эксперта по результатам отработки замечания |
8 | Статус исполнителя | Статус отработки замечания техническим писателем (например, Выполнено / Отклонено / В работе / Снято автором и т.д.) |
9 | Дата статуса исполнителя | Дата отработки замечания техническим писателем |
10 | Исполнитель | Фамилия Имя (Отчество) технического писателя |
11 | Статус автора | Статус подтверждения отработки замечания после проверки автором (например, Принято / Отклонено) |
12 | Дата статуса автора | Дата подтверждения отработки замечания автором |
13 | Комментарий автора | Комментарий функционального эксперта к ответу технического писателя при отработке замечания (например, по мнению автора замечание устранено не полностью) |
Результат выполнения шага процесса “Разработка”:
-
подготовлена первая версия документа в соответствии с разработанной структурой;
-
подготовлен шаблон реестра замечаний (для отработки возможных замечаний функциональных экспертов на этапе согласования).