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

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

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

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

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

---

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

00:00 - 01:08 Приветствие

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

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

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

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

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

Этот процесс состоит из следующих этапов:

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

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

01:09 - 01:42 Этап “Подготовка”

Тема сегодняшнего выпуска - подготовка.

Данный шаг является, пожалуй, самым важным во всём процессе. Насколько качественно выполняются подготовительные работы, настолько качественно выполняется целевая задача по разработке документации.

В свою очередь, этап подготовки может быть разделён на детальные шаги:

1. Планирование.
2. Исследование.
3. Технологическое оснащение.

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

01:43 - 06:09 Планирование

Любое дело начинается с планирования. Будь то строительство дома, поездка в отпуск или разработка ИТ-продукта. В самом начале пути важно понять и разобраться, как минимум, в следующих вопросах - что должно получиться в итоге, для кого и зачем это что-то будет сделано, как это сделать.

Ведь нельзя же, например, привезти на участок сколько-то упаковок кирпичей, ещё какой-то объём песка, немного цемента, десяток рабочих и, показав им красивую картинку из журнала, сказать: “Сделайте так же!”.

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

Написание документации пойдёт достаточно легко только при наличии хорошего плана.

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

Итак, пункты плана:

Структура плана разработки технической документации

№ п/п	Пункт плана	Пояснение
1	Цель	Здесь указывается однозначное и понятное описание цели разработки документации (например, разработка пакета эксплуатационной документации для системы аналитической отчётности по выполнению показателей эффективности ремонтной деятельности предприятия)
2	Объём	В данном пункте представляется перечень документов, которые будут разработаны. Это может быть как один, так и несколько документов в рамках пакета документации (например, руководство администратора системы, руководство пользователя системы, инструкция по сверке показателей)
3	Нормативные требования	В нормативных требованиях указывается перечень нормативных документов, которые применяются в разработке системы и работе пользователей (например, ГОСТы, методические указания предприятия и т.д.)
4	Целевая аудитория	Описание представителей целевой аудитории для каждого из документов пакета, если документов несколько (например, сотрудники службы второй и третьей линий поддержки, сотрудники департамента финансового контроля)
5	Зависимости	В данном пункте перечисляются возможные смежные задачи, которые оказывают влияние на разработку технической документации (например, доработка и тестирование определённого функционала системы). То есть пока не окончены смежные работы, не могут начаться задачи по документированию этого функционала
6	Ограничения	Описание возможных ограничений, которые могут накладываться на выполнение задач по разработке документации (например, бюджет, срок реализации и т.д.)
7	Контрольные точки	Это перечень контрольных дат, позволяющий отслеживать ход реализации разработки документации (например, дата первой версии документа, дата финальной версии документа и т.д.)
8	Участники и роли	Здесь указывается перечень участников и их ролей в процессе разработки документации (например, функциональный заказчик, предметные (функциональные) эксперты по продукту, аналитики, технические писатели и т.д.)
9	Связанные документы	Перечень проектных документов, созданных при разработке продукта (например, функциональные требования, технический проект, спецификации и т.д.)

06:10 - 07:45 Исследование

После того, как работы по планированию закончены, наступает время изучения продукта и поиска сокровенных знаний о нём. Другими словами, приходит время исследований.

Исследования можно разделить на два типа:

• предметные,
• оформительские.

Предметные исследования

К предметным исследованиям относится погружение в продукт и его детали. На данном этапе изучается вся имеющаяся связанная документация, непосредственно сам объект (предмет) документирования, проводятся интервью с предметными (функциональными) экспертами. Также подробно изучаются процессы, связанные с объектом документирования.

Таким образом, набирается огромный объём информации для дальнейшей работы.

Оформительские исследования

Достаточно часто на этом исследования заканчиваются. Но до поры до времени остаётся открытым один вопрос - оформление документации.

Во многих компаниях приняты свои требования к оформлению технической документации. Например, соответствие ГОСТам, корпоративным стандартам или руководствам по стилю.

С моей точки зрения, желательно ознакомиться с соответствующими рекомендациями заранее, до начала разработки документов.

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

07:46 - 10:30 Технологическое оснащение

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

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

Набор инструментов для разработки техдокументации

№ п/п	Инструмент	Пояснение
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 и др.

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

10:31 - 11:04 Результат этапа “Подготовка”

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

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

11:05 - 11:53 Заключение

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

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

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

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

Пока!