Клуб технических писателей

Клуб технических писателей

Структура единого источника

В некоторых задачах имеет смысл использовать как пользовательский, так и проектный контент.

Понимаю, что, скажем, содержание технического задания или устава IT-проекта скорее всего НЕ подойдет для руководства пользователя или руководства администратора, но вот, например, для руководства программиста — возможно!

Под единым источником я понимаю структурное хранилище единиц документации в той или иной форме: ядро проекта, файлы XML (для DocBook или H&M), заготовки в MS Word и т. д.

Что может быть единым (использоваться и там, и здесь):

1. Для данной задачи, скорее всего, подойдет единая терминология проекта, которая может из проектной документации "перекочевать" в пользовательскую.

2. Перечень функций, описанных в техническом задании, может "перейти", например, в руководство программиста, а затем — при незначительных правках или фильтрации контента — в итоговое руководство.

3. Описание полей таблиц — в приложения соответствующих руководств или в контекстную справку.

4. Перечень ответственных с их задачами и обязанностями — в технологическую инструкцию и т. д.

Насколько на Ваш взгляд оправданы затраты на такое "совместное" использование контента; если кто-то уже использует подобное решение, не могли бы поделиться опытом?

Заранее спасибо!

10 комментариев
Авторизуйтесь, чтобы оставить комментарий
Юлия Кухмай
28 января 2016, 03:15

Для начала скажу, что реюз - это прекрасно :) Возможно, на начальном этапе кажется, что это трудозатратнее. Если собираешься использовать топик повторно, он должен быть идеальным - выверенным, логически завершенным, полным, самостоятельным, т.е. такой "вещью в себе". Т.е. держать в голове, что он должен вписываться в контекст других документов. Обычно такой идеал достигается далеко не за один подход :)

Но дальше это здорово упрощает жизнь. Если что-то изменяется, то меняешь только в одном месте, и не думаешь, в каком еще документе была описана функциональность.

Мы используем реюз как на уровне комплекта документов на одну систему, так и более глобально — на уровне всех продуктов компании.

Глобальный реюз:

- термины и определения. Идеально, когда термин един. Если есть особенности определения для какой-то системы, используем фильтрацию.

- общие разделы в документах (о компании, обратная связь, техподдержка и т.п);

На уровне комплекта документов:

- Описание БД (таблицы, пакеты),

- Описание параметров

- Общая информация о компоненте/ системе.

- Другие общие для нескольких документов топики.

bryston
28 января 2016, 03:15

Спасибо за ответ!

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

Сложность возникает, когда документы готовят разные сотрудники: сметно-финансовые — юристы, финансисты, секретари, проектные — менеджеры, аналитики, архитекторы, пользовательские — технические писатели, переводчики, сотрудники техподдержки. Как Вы решили этот вопрос? Может есть смысл делать "выжимку" из всех документов проекта в части информации для единого источника, а затем на завершающем этапе — ВСЕ техпису?

Мы используем реюз как на уровне комплекта документов на одну систему, так и более глобально — на уровне всех продуктов компании.

Вы пишите о комплекте пользовательской документации разных видов, версий и языков или комплекте всего цикла: договорно-финансовые отношения, проектирование, поддержка?

Юлия Кухмай
28 января 2016, 03:15

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

Если у вас есть возможность подключить всех, так тем лучше - топики будут выверены на всех уровнях :)

bryston
28 января 2016, 03:15

Спасибо; известно по опыту работы в DocBook :)

Это сложно "всех объединить", хотя через промежуточное звено типа MS Word!!!

А как Вы решили вопрос со схожими наименованиями? Например, в различных таблицах есть следующие поля: "Клиент", "Юридическое лицо", "Контрагент", у которых схожие определения. Ваша схема работы позволяет реализовать справочный принцип работы (в одном месте исправили поле "Клиент" и т. д., везде обновились данные, но вот возникает вопрос о наименованиях полей... было бы здорово иметь некие локальные переменные с наименованими полей; если поле "Клиент" стало называться "Клиент продукта", надо изменить только значение одной переменной). Или Вы каждое такое изменение ищете в соответствующих XML, чтобы заменить?

Юлия Кухмай
28 января 2016, 03:15

Привет! Для таких случаев в DITA есть чудесный механизм контекстных ссылок (conkeyref или conref, мы работаем только с ключами - conkeyref). Создаете топик, в нем элемент, который будуте реюзать. Если это просто название, то удобно заключить его в теги (фраза). На элемент (или фразу) назначаете id. Всё - элемент доступен для реюза. Далее - вопрос техники и редактора DITA, который вы используете. Меняется название элемента в исходном топике - меняется везде, откуда есть на этот элемент ссылка. 

Чтобы в исходном топике было видно, что его элементы где-то используются, я добавляю комментарии. Чтобы бездумно не править исходные элементы.

bryston
28 января 2016, 03:15

Удобная возможность!

eduard-tibet
28 января 2016, 03:15

Bryston, вы же использовали Docbook. А значит и должны знать, что там это решается при помощи XInclude+Xpath + оlinks (если необходимо)

bryston
28 января 2016, 03:15

Спасибо, Эдуард!

Мне интересна идея совместного использования проектного и пользовательского контента, но в DocBook все было только для руководств пользователей...

eduard-tibet
28 января 2016, 03:15

Вы немного не поняли суть моего ответа. Речь шла о том, что для reuse content в Docbook используется те механизмы, о которых я написал НЕЗАВИСИМО от того, какой именно именно контент (prj или usr используется).

P.S. Кстати, мне странно, что в руководствах пользователя вы не делали reuse (а как же, например, системные требования? требования к персоналу?).

bryston
28 января 2016, 03:15

Наоборот, делал, как без ре-юза :)

Вопрос об опыте коллег...