После выполнения шага “Подготовка” осуществляется переход к разработке документации.

Разработка так же может быть разделена на более детальные шаги:

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

Шаги подпроцесса Разработка

Структурирование

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

Существует несколько подходов структурирования технической документации.

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

Если представить пример инструкции по сверке показателей (какого-то процесса). Скорее всего, каждый показатель будет обладать определённым набором атрибутов (наименованием, формулой расчёта, другими более мелкими (базовыми) показателями и т.д.)

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

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

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 Комментарий автора Комментарий функционального эксперта к ответу технического писателя при отработке замечания (например, по мнению автора замечание устранено не полностью)

Результат выполнения шага процесса “Разработка”:

  • подготовлена первая версия документа в соответствии с разработанной структурой;

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