Выпуск #4. Дополнение по единому источнику правды

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

Небольшое дополнение к выпуску о едином источнике правды документации.

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

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

---

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

00:00 - 00:51 Приветствие

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

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

Сегодня на календаре 16 марта 2023 года.

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

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

00:52 - 01:30 Беседа с коллегой

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

Говорили о многоцелевом использовании контента. Имеется в виду, что документация может быть доступна в различных форматах. Например, как у нас в компании - одновременное использование документации на веб-портале и в печатном формате (точнее в виде файлов PDF или DOC/DOCX).

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

01:31 - 02:19 Проектирование - ожидание и реальность

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

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

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

02:20 - 03:21 Варианты сопровождения документации

По каждому документу провели анализ и в результате получили три варианта сопровождения и развития нашей документации:

1. Полное дублирование.
2. Частичное дублирование.
3. Отсутствие дублирования.

Полное дублирование подразумевает то, что один и тот же документ мы создаем и поддерживаем в Confluence и в виде отдельных файлов в формате PDF/DOCX/XLSX.

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

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

03:22 - 04:34 Резюме

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

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

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

04:35 - 05:15 Заключение

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

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

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

Пока!