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

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

Техкомпод на Apple Podcasts Техкомпод на Google Podcasts Техкомпод на Яндекс Музыке

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



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

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. Я периодически пишу там заметки по техписьму и коммуникациям. И конечно же подписывайтесь на подкаст.

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

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

Пока!



Оповещение о новых выпусках

Получайте оповещение о публикации новых выпусков подкаста. Никакого спама. Всего одно письмо в две недели.