Выпуск #2. Единый источник правды

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

Как развивалась техническая документация? Что такое единый источник правды? Ответы на эти вопросы в данном выпуске подкаста.

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

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

---

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

00:00 - 00:59 Вступление

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

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

Сегодня на календаре 16 февраля 2023 года.

Выпуск номер два.

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

01:00 - 02:33 Краткое описание эволюции техдокументаци

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

Когда-то на заре технического писательства (не берём в расчёт времена Аристотеля, а также средние века) документацию создавали с помощью пишущих машинок и только на бумаге. И был это очень тяжёлый труд.

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

Далее появился межплатформенный формат электронных документов - PDF, в котором также стали хранить и публиковать документацию.

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

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

Сейчас, как известно, на острие эволюции находится подход к разработке документации “doc-as-code” или “doc-like-code” - “документация как код”, который использует такие же процессы и инструменты, что в разработке программного обеспечения.

02:24 - 03:37 Подход “doc-as-code” в России и опыт Ozon

Если говорить про российский рынок, то подход “документация как код” применяют не такое уж большое количество компаний. К тому же, не всем это подходит. Да и по правде говоря, не всем это нужно. Как правило, подход “документация как код” внедряется в продуктовых компаниях, которые разрабатывают какой-то свой собственный продукт. Это может быть что угодно: приложение, сервис, информационная платформа и т.д. В качестве примера здесь можно привести Ozon.

Кстати, рекомендую прочитать на хабре статью Кати Ушаковой - руководителя отдела технических писателей Ozon - о том, как они меняли инструменты и процессы ведения документации. В своей статье Катя подробно рассказала, как они перенесли часть документации из Confluence на статические генераторы сайтов, а также каким образом перешли на парадигму “doc-as-code”.

Статья называется Делаем документацию здорового человека в Git на примере Docs Ozon.

03:38 - 06:23 Хранилище документации

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

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

В процессе миграции и анализа существующей документации мы выявили многократное дублирование одинаковой информации в разных документах.

Так как основной профиль нашей команды - разработка хранилищ данных, мы решили заимствовать некоторые принципы организации корпоративных хранилищ данных в организации портала технической документации.

В частности, один из основных принципов хранилища данных - «единый источник правды». Хранилище служит источником выверенной информации для принятия решений руководством в различных областях деятельности компании. Одни и те же данные, но в разных разрезах могут быть использованы разными подразделениями компании.

Архитектура хранилища представляет собой набор, так называемых слоёв или уровней. Но для реализации идеи по хранилищу документации нам требовались не все эти уровни. Поэтому оставили только следующие два:

• уровень распространения данных,
• уровень бизнес-трансформации данных.

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

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

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

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

06:23 - 09:36 Методология единого источника правды

Вообще, методология единого источника правды документации заключается в следовании двум принципам: Повторное использование содержимого документации Многоцелевое использование содержимого документации

Суть первого принципа я привёл ранее на примере развития документации в нашей компании. Это когда существует единое логическое пространство, где хранится и ведётся детальная информация. И уже из этого логического пространства информация импортируется (или повторно используется) в различные документы.

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

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

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

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

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

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

Если Вы уже решали подобные задачи, пожалуйста, поделитесь опытом.

09:37 - 10:13 Резюме

Если подвести итог основной сегодняшней темы, то получается следующее.

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

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

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

10:14 - 10:56 Заключение

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

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

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

Пока!