Впровадження технології єдиного джерела DITA у компанії-розробника

Доброго дня! Мене звуть Олена Толмачова. У компанії «ДоксВижн» я займаюся розробкою користувальницької документації.

Останнім часом для створення різного роду інструкцій з експлуатації складних програмних систем все більш популярним стає використання технології єдиного джерела, що передбачає повторне використання в розробляється комплекті документів будь-яких текстів або зображень. Не так давно для розробки довідок і друкованих документів «ДоксВижн» ми стали застосовувати дану технологію, і в цій статті я хочу поділитися отриманим досвідом.



Чому ми обрали технологію єдиного джерела?
Тим, хто знайомий з компанією «ДоксВижн», відомо, що основним розробляються нами продуктом є платформа Docsvision, а крім неї випускається безліч додаткових програм та модулів. Так як допоміжні продукти призначені для використання у складі платформи, при описі дій користувача в документації частину тексту нам доводилося дублювати: або повністю, або з незначними змінами. Такий підхід (з урахуванням регулярного випуску нових версій для всіх продуктів) був дуже трудомісткий для технічних письменників, т. к. величезний обсяг наявних описів не дозволяв нам відслідковувати зміни у всіх повторюваних розділах і оперативно вносити зміни до безліч документів.

Були й інші труднощі:

• Редактор, в якому виконувалась розробка, не мав на увазі одночасної роботи з документом кількох техписателей, що ускладнювало організацію командної роботи над проектом.
• Замовники зверталися в компанію з проханнями надання документів в різних форматах: одні воліли довідки, іншим потрібна була можливість редагування або друку. Ми ж не мали такої можливості.
• Ще нам хотілося, щоб всі випускаються документи виглядали в одному стилі. Але через людського фактора ми ніяк не могли цього досягти: надається шаблон документа дозволяв вносити зміни, і його регулярно хтось міняв на свій розсуд, що псувала загальне враження від документів компанії.

В момент, коли кількість мінусів переповнило чашу нашого терпіння, було прийнято рішення кардинально змінити спосіб розробки документів. В результаті ми зупинили свій вибір на технології єдиного джерела, а конкретно — вирішили використовувати в роботі DITA-архітектуру.

Чому саме DITA
Технологія DITA нам сподобалася з кількох причин. Ця архітектура розроблялася спеціально для технічних письменників, і багато потреби творців документації в ній вже були враховані. Для нас визначальними факторами виявилися наступні:

• можливість випуску документів в різних форматах (PDF, HTML5 та XHTML, Eclipse Help, TocJS, HTML Help, Java Help, ODЕ, RTF, troff),
• жорстке структурування розділів за рахунок типізованих «топіків» (concept, task, reference та ін)
• можливість одночасної роботи над проектом декількох співробітників.

Ми обрали технологію і приступили до складання плану її впровадження.

Планування
На початку шляху ми склали якийсь план, який по ходу справи, безумовно, довелося коригувати. Тут же я наводжу набір етапів у суворій послідовності виконання, який (на нашу думку) є оптимальним для вирішення поставленого завдання. Звертаю увагу, що план підійде при переході на будь-яку технологію єдиного джерела (не тільки обрану нами DITA).

Етапи нашого плану такі:
1. Інструменти
2. Стандартизація
3. Дизайн
4. Налаштування
5. Зберігання
6. Навчання

Нижче я детально опишу всі ці етапи. І давайте згадаємо тих фахівців, які можуть надати допомогу при впровадженні. Нам при переході на нову систему знадобилися:
• Дизайнер — допоміг підготувати макети дизайну для документів
• Програміст — налаштував інструмент для складання документа в кілька форматів
А координував всі ці роботи технічний письменник.

Інструменти
Нова технологія передбачає використання нових програмних засобів, тому на першому етапі впровадження потрібно буде вибрати і придбати деякий софт. Як мінімум, вам знадобиться:
• редактор для технічних письменників (ми вибрали Oxygen XML Author)
• інструмент для складання документів з вихідного формату в підсумковий (ми вибрали DITA Open Toolkit, щоб перетворювати файли формату XML у поставляються формати pdf і xhtml)
• система зберігання для вихідних файлів і підсумкових документів (ми вибрали TFS)

При виборі редактора варто спиратися на зручність його використання, наявність функцій для виконання необхідних завдань і, звичайно, вартість професійної версії. Зазначу, що підтримка роботи з DITA реалізована майже у всіх найпопулярніших редакторах для технічних письменників (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).

Вибір інструменту для складання документа може і не знадобитися, якщо придбаний редактор дозволяє збирати документ в необхідному для випуску форматі і оформленні. Під оформленням в даному випадку я маю на увазі стандарт, прийнятий у Вашій компанії: шрифти, логотипи, кольорове оформлення, формат підсумкових документів тощо

Система зберігання може застосовуватися та ж сама, яку розробники у Вашій компанії використовують для зберігання програмного коду — в цьому випадку можна заощадити на придбанні. Потрібно лише придумати вдалий спосіб організації сховища, про який я розповім нижче.

Стандартизація
На другому етапі впровадження потрібно виконати стандартизацію документів. В першу чергу, щоб домогтися однаковості структури документації, а також, щоб можна було сформувати завдання дизайнеру на стильове оформлення.

Що потрібно стандартизувати:
• типи документів, які будуть випускатися по кожному з продуктів компанії (керівництво користувача, керівництво адміністратора і тд)
• структуру документа для кожного з допустимих типів (титульний лист, вступ, розділи, розділи, список документів, додатки)
• склад елементів для кожного елемента структури (наприклад, для титульного аркуша: логотип, назва продукту, системи, версія, тип документа)
• перелік підсумкових форматів (pdf, odt, xhtml і т. д.)
• перелік локалізацій (російську, англійську і т. д.)
• спосіб нумерації версій продукту та випущених версій документів по продукту

Поясню, для чого потрібен такий жорсткий стандарт. В якості прикладу розглянемо титульний аркуш документації Docsvision, який у довідці та друкованому форматі, хоч і виглядає в одному стилі, але різниться за складом елементів та способу оформлення. Наприклад, у довідці буде присутній опис призначення документа (яке в друкованому форматі розташовується не на титульному аркуші, а в розділі «Вступ»), у полі пошуку та зміст. Зверніть увагу, що інший текст цих листів повністю збігається, визначається стандартом і не залежить від стилю.


Рис. 1. Приклад складу елементів титульного аркуша

Створення стандарту — це, мабуть, найважливіший етап впровадження, адже помилки стандартизації потім плавно перетечуть у макети дизайну, а звідти — в програму для складання підсумкових документів. Якщо помилок буде багато, всю роботу доведеться починати заново.

Дизайн
На етапі дизайну необхідно підготувати графічні макети документації, щоб на етапі налаштування інструменту для складання документа у програміста було чітке розуміння, як повинна виглядати web-сторінка довідки або лист друкованого формату.

Бажано заздалегідь ознайомити дизайнера з використовуваним в компанії Довідником стилів, а якщо раптом його немає (таке буває часто), то хоча б з сайтом компанії.

Макети потрібно підготувати:
• для кожного з стандартизованих раніше форматів підсумкових документів, наприклад, окремий набір картинок для pdf і окремий набір картинок для xhtml-довідки
• для кожного їх стандартизованих варіантів стильового оформлення (наприклад, якщо у відповідності зі стилем компанії для продуктів використовується різна колірна гама)
• для кожного з стандартизованих мов (на іноземних мовах буде використовуватися інша термінологія, програміст може не знати, до прикладу, перекладу слова «Пошук» на французьку мову)

Підготовлені макети слід узгодити з керівництвом компанії і після цього можна перейти до етапу налаштування.

Налаштування
Як я вже попереджала, для виконання налаштування, ймовірно, доведеться підключати програмістів різної спеціалізації. Для складання довідок потрібні знання СSS, і оптимальним буде залучення спеціаліста з верстки. А для налаштування виводу друковані формати тільки верстки може виявитися недостатньо. Наприклад, для настроювання використовуваного нами інструменту Dita Open Toolkit для складання у формат PDF був потрібен фахівець, знайомий з XSLT перетвореннями.

Я не знаю, які саме програмісти вам потрібні. Але в будь-якому випадку, слід враховувати такі важливі фактори:
• скільки форматів буде збирати готова програма з наданих технічним письменником вихідних файлів
• скільки варіантів стильового оформлення можна зібрати однією програмою або потрібно кілька програм для різних стилів
• скільки мов програма буде підтримувати, і можна буде простим налаштуванням змінити мову виводу

Приклад того, як визначити кількість коштів, складання документації, наведений на малюнку.


Рис. 2. Варіанти настройки програми для складання документації

При розрахунку часу, відведеного на програмування, враховуйте, що часто цей процес затягується не на один місяць. Під час роботи документатору можуть знадобитися нові таблиці, заголовки і так далі, і тоді програму доведеться доопрацьовувати.

Зберігання
Технологія єдиного джерела увазі, що вихідні файли документа (створюються технічними письменниками) і готові документи (створювані програмою для складання документа) — це різні файли. І зберігатися ці файли повинні теж окремо. Оптимально використовувати ту саму систему зберігання версій, що і розробники програмного коду вашої компанії.


Рис. 3. Принцип зберігання файлів в технології єдиного джерела

Структура зберігання вихідних файлів повинна будуватися за таким принципом:
• спосіб зберігання файлів для всіх технічних письменників повинен бути єдиним,
• назви документів повинні бути стандартизовані,
• версії випускаються документів не повинні перетинатися,
• довідки, зібрані автоматично разом з програмним кодом, повинні зберігатися там же, де і код.

Структура зберігання підсумкових документів повинна передбачати:
• роздільне зберігання різних версій;
• в рамках версії:
— роздільне зберігання для різних форматів;
— роздільне зберігання для різних локалізацій.

Навчання
На заключному етапі впровадження вам необхідно буде навчити колег роботі з новою технологією.

В першу чергу, технічних письменникам потрібно освоїти новий редактор для написання тексту.
Ймовірно, буде потрібно також вивчити список тегів, які будуть оброблятися програмою для складання документації. Наприклад, в «ДоксВижн» ми використовуємо теги специфікації DITA.
Якщо до переходу на використання технології єдиного джерела частину тексту копіювалася, тепер його можна і потрібно буде навчитися використовувати повторно. Плюс до того, колег потрібно ознайомити з новими структурами зберігання даних і уважно стежити за тим, щоб цей стандарт усіма дотримувався.

Що в підсумку
Якщо впровадження буде успішним, якість розроблюваної документації значно підвищиться, а витрати на її виробництво зменшаться. Технічні письменники будуть отримувати більше задоволення від своєї роботи, а їх керівники — позитивні відгуки від партнерів.

На закінчення скажу, що, в середньому, впровадження технології єдиного джерела займає близько півроку, а ще стільки ж часу займе перенесення раніше розроблених документів у новий формат.

Сподіваюся, цей матеріал виявиться для вас корисним і допоможе перейти на нову технологію швидко і безболісно!

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.