Рабочий процесс технического писателя. Подготовка
Подготовка является, пожалуй, самым важным шагом в рабочем процессе технического писателя.
Насколько качественно будут выполнены подготовительные работы, настолько качественно будет выполнена целевая задача по разработке документации.
В свою очередь, подготовка может быть разделена на более детальные шаги:
- Планирование.
- Исследование.
- Технологическое оснащение.
Планирование
Любое дело начинается с планирования. Будь то строительство дома, поездка в отпуск или разработка ИТ-продукта. В самом начале пути важно понять и разобраться, как минимум, в следующих вопросах:
- Что должно получиться в итоге?
- Как это сделать?
- Для кого и зачем это что-то будет сделано?
Ведь нельзя же, например, привезти на участок сколько-то упаковок кирпичей, ещё какой-то объём песка, немного цемента, десяток рабочих и, показав им красивую картинку из журнала, сказать: “Сделайте так же!”. Хотя всё-таки можно, но вот результат без должного планирования и расчётов вряд ли будет сопоставим с первоначальными ожиданиями. С технической документацией ровно та же история.
Планирование - одна из самых сложных задач технических писателей. Написание самих документов пойдёт достаточно легко, но только при наличии хорошего плана.
Поэтому разработка техдокументации тщательно планируется, а главным документом на данном шаге является план разработки технической документации, который включает в себя представленные в таблице пункты.
| № п/п | Пункт плана | Пояснение |
|---|---|---|
| 1 | Цель | Описание цели плана (например, разработка пакета эксплуатационной документации для системы аналитической отчётности по выполнению показателей эффективности ремонтной деятельности предприятия) |
| 2 | Объём | Перечень документов, которые будут разработаны в рамках пакета документации (например, руководство администратора системы, руководство пользователя системы, инструкция по сверке показателей) |
| 3 | Нормативные требования | Перечень нормативных документов, которые применяются в разработке системы и работе пользователей (например, ГОСТы, методические указания предприятия и т.д.) |
| 4 | Целевая аудитория | Описание представителей целевой аудитории для каждого из документов пакета (например, сотрудники службы второй и третьей линий поддержки, сотрудники департамента финансового контроля) |
| 5 | Зависимости | Перечень возможных смежных задач, которые оказывают влияние на разработку технической документации (например, доработка и тестирование определённой функциональности системы) Пока не окончены смежные работы по функциональности, не могут начаться задачи по документированию этой функциональности |
| 6 | Ограничения | Описание возможных ограничений, которые могут накладываться на выполнение задач по разработке документации (например, бюджет, сроки реализации и т.д.) |
| 7 | Контрольные точки | Перечень контрольных дат, позволяющий отслеживать ход реализации плана разработки документации (например, дата первой версии документа, дата финальной версии документа и т.д.) |
| 8 | Участники и роли | Перечень участников и их ролей в процессе разработки документации (например, функциональный заказчик, предметные (функциональные) эксперты по продукту, аналитики, технические писатели и т.д.) |
| 9 | Связанные документы | Перечень проектных документов, созданных при разработке продукта (например, функциональные требования, технический проект, спецификации и т.д.) |
Исследование
После того, как работы по планированию закончены, наступает время изучения продукта и поиска сокровенных знаний о нём. Другими словами, приходит время исследований.
Исследования можно разделить на два типа:
- предметные,
- оформительские.
Предметные исследования
К предметным исследованиям относится погружение в продукт и его детали.
На данном этапе изучается вся имеющаяся связанная документация, непосредственно сам объект документирования, проводятся интервью с предметными (функциональными) экспертами. Также подробно изучаются процессы, связанные с объектом документитрования.
Таким образом, набирается огромный объём информации для дальнейшей работы.
Оформительские исследования
Достаточно часто данный тип исследования долгое время остаётся открытым один вопрос. Изучению требований по оформлению документации не придаётся должного значения.
Во многих компаниях приняты свои требования к оформлению технической документации. Например, соответствие ГОСТам, корпоративным стандартам или руководствам по стилю. Было бы очень уместно ознакомиться с соответствующими рекомендациями заранее, до начала разработки документов.
Оформительские исследования, в первую очередь, актуальны для техписателей-фрилансеров, которые участвуют в проектах у различных заказчиков, а также для техписателей-новичков, начинающих свой путь в какой-то организации. В остальных случаях, как правило, используется “выверенный” корпоратиный шаблон документа.
Технологическое оснащение
Заключительным шагом в планировании является подготовка технологического оснащения (оснастки), то есть проверка необходимого программного обеспечения (ПО) для выполнения поставленных задач.
Набор инструментов для разработки технической документации может различаться от компании к компаниях, но всё-таки их можно сгруппировать, чтобы получить общее представление о “базовом” комплекте (за исключением специального программного обеспечения, которое относится непосредственно к документируемому объекту).
| № п/п | Инструмент | Пояснение |
|---|---|---|
| 1 | Текстовый редактор (процессор) | Основной и наиболее популярный инструмент технических писателей. Используется для набора, сохранения, редактирования текста, создания таблиц, вставки графических изображений и т.д.
Примеры: Microsoft Word, OpenOffice Writer, LibreOffice Writer, Google Docs и др. |
| 2 | ПО для обработки и редактирования изображений | Данный тип ПО используется техническими писателями для подготовки и оформления скриншотов, сопровождающих документацию.
Примеры: Windows Ножницы, Microsoft Paint, GIMP, Adobe Photoshop и др. |
| 3 | Система управления содержимым (CMS) | CMS используется для обеспечения и организации совместного процесса создания, редактирования документации несколькими техническими писателями. В основном применяется в крупных компаниях.
Примеры: WordPress, easyDITA и др. |
| 4 | Интегрированная среда разработки (IDE) | IDE применяется при создании и поддержке технической документации с использованием инструментов и процессов, которые применяются в разработке программного кода смежной командой разработчиков. Является одним из признаков концепции под названием “документация как код” (“docs as code”).
Примеры: Atom, Sublime Text, Visual Studio Code и др. |
Текстовые редакторы (процессоры) в связке с программами обработки и редактирования изображений являются “джентльменским набором” технического писателя. Это понятные, простые и функциональные инструменты, позволяющие эффективно выполнить свою работу.
Перечень инструментов, разумеется, может изменяться и дополняться в различных компаниях.
Результат выполнения шага процесса “Подготовка”:
-
сформирован, согласован и утверждён (функциональным заказчиком) план разработки технической документации;
-
проведены необходимые исследования в части продукта и требований оформления документации;
-
проверен и установлен на рабочий компьютер стек технологий (набор инструментов, применяющийся при работе) для разработки технической документации.