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