| Цитата |
|---|
| Лучше начните изучать Диту. За ней будущее, а не за отживающим свой век Докбуком |
Это утверждение ярко иллюстрирует непонимание места DITA при разработке документации.
В своем длинном письме я не буду обсуждать ваши утверждения (с вами мне всё ясно),
а просто поясню очень кратко (типа “Апрельских тезисов В. Ленина”) для участников форума суть разного подхода к обсуждаемой теме – внедрение DITA.
Будут рассмотрены вопросы:
- Технология DocBook -это просто;
- DITA – это тот же DocBook с дополнительным функционалом;
- Чем DITA отличается от DocBook?
- В каких случаях надо использовать (или вообще не использовать) DocBook или DITA?
- Функции и обязанности TW при освоении указанных технологий;
- 6 Выводы.
Технология DocBook1 Готовый исходный текст (в формате txt) или вводимый с клавиатуры в любом текстовом редакторе (типа Notepad) или специализированном XML-редакторе (их множество) размечается с помощью атрибутов (их, стандартных, несколько сотен; если не хватает, можно придумать свои) – например <кнопка>, <пункт меню>, <клавиша>, <командная строка>, <имя файла> и т. п.).
2 Структура документа должна соответствовать его DTD-схеме (стандартная DTD-схема покрывает 99% видов программных документов и придумывать ничего не надо).
3 Размеченный документ конвертируется с помощью встроенных конверторов в нужные форматы: html (полный и секционный ), winhelp, ebook, pdf и др.
4 Если принятые по умолчанию стили оформления выходного документа не устраивают, то их можно настроить с помощью таблицы стилей CSS (для html документов).
(К сожалению, формат PDF не поддерживает CSS, поэтому настройка стилей для PDF выполняется путем модификации xsl-файлов, используемых при конвертации).
5 Если параметры конвертирования по умолчанию не устраивают, их можно настроить в xsl-файле (docdook.xsl, param.xsl ). Параметры конвертирования аналогичны параметрам Word (например, уровень оглавления, подписи вверху или внизу рисунка, вид ссылки на рисунок – только номер и/ или название и т.п.).
6 Для освоения этих процессов знание языка XSL (и XSLT как его подмножества) не требуется.
При грамотном методическом подходе и наличии соответствующей документации технология осваивается за неделю.
DITA – это тот же DocBook Как я уже писал ранее, продукты DITA и DocBook – это плоды одной и той же фирмы.
Поэтому используются одни и те же механизмы и программы для подготовки и конвертации в различные форматы. Следовательно, овладев DocBook, легко овладеете и DITA.
Чем DITA отличается от DocBook ?DITA – это расширение DocBook в части механизма компоновки документов.
DocBook позволяет компоновать документ (книга, статья) из фрагментов, оформленных в виде отдельных XML-файлов. Просто в файле книги (статьи) вы перечисляете их в нужном порядке с помощью конструкции <!ENTITYY>. Есть возможность логически включать (исключать) фрагменты (так называемое “профилирование”).
Технология DITA это механизм развила дальше, сделав его более удобным с помощью дополнительных программных средств.
Т.е. она подразумевает составление документа как мозаики из заранее подготовленных небольших фрагментов (топиков) по аналогии с разбиением документа на топики при создании help- систем). Порядок размещения таких топиков (т. е. структура документа) описывается в специальном файле – карте документа.
После того как DITA обработает карту документа (т. е. заменит ссылки на топики их содержимым) мы получим исходный XML-документ - придем к технологии DocBook, т. е. дальше применяется уже чистая DocBook технология (используются те же программы Apache Ant, Fop и т. п.).
Т. е. DITA – надстройка над DocBook. Зная технологию DocBook (1 неделя на освоение) прибавьте еще 1 неделю на DITA. Столько теоретически требуется для освоения DITA (практически – несколько больше, но об этом ниже).
В каких случаях надо использовать (или вообще не использовать) DocBook или DITA ?Целесообразность использования DocBook:
1 Документацию надо иметь одновременно в нескольких форматах (например, html, winhelp, PDF и др.), причем исходная документация часто меняется. Затратив большие усилия на первоначальную разметку документа дальше легко и просто можно конвертировать его в нужные форматы.
Если же вам необходимо конвертировать исходный документ только в один какой-то формат (например, PDF), то вместо DocBook лучше использовать другие специализированные пакеты (например, Adobe Acrobat), который позволяет из Word получать печатные и электронные PDF-документы высокого качества и не заморачиваться XML-разметкой.
Использование технологии DITA становится экономически (и технологически) оправданным только при разработке документации очень большого объема, с большим количеством повторяющихся (однотипных) фрагментов текста и при коллективной (совместной) разработке документа (одни пишут профессионально функционал, другие техническую часть, третьи еще что).
Например, завод выпускает 100 моделей сотовых телефонов, соответственно, нужно иметь 100 разных инструкций по эксплуатации. Но во всех этих инструкциях есть много общих описаний (работа с календарем, с телефонной книгой и т. п.) и есть индивидуальные отличия.
В этом случае разрабатывается набор топиков (исходных фрагментов) текста, а каждая инструкция - это просто карта (в терминах DITA) из этих топиков.
В случае изменения в описании какого-то топика это изменение автоматически попадает во все инструкции, где этот топик задействован.
Функции и обязанности TW при освоении указанных технологий Здесь нас пугают страшилками о трудностях освоения технологии DITA (или DocBook).
Это неправда. При правильной организации работы и при действительной необходимости в использовании DITA процесс освоения не столь длительный и мучительный.
Ничего принципиально нового (отличного от повседневной работы TW - написание фрагментов текста и структурирование документа) они не привносят. Просто появляются новые (не сложные) способы выполнения этой работы.
Но это только в том случае, если на TW не возлагают:
- Установку (и конфигурирование) ПО для работы DITA (сложный и плохо документированный процесс) и DocBook (например, Exlipse). Эту работу должен выполнять профессионал - системный программист. Это не обязанность TW (или всей бригады TW), ибо для установки, например, Eclipse надо установить сначала JAVA- платформу и для JAVA настроить операционную систему и т. д. Если специалист делает это за 2 часа, то TW может делать очень долго или вообще ничего не сделать.
- Рекомендация изучить язык XSLT. Все указанные технологии предоставляют готовые средства и шаблоны, которые выполняют конвертирование в разные форматы. Эти средства покрывают 99 % всех потребностей. Необходимость в изучении XSLT возникает тогда, когда надо написать собственный специфический конвертор (например, в некий экзотический формат ABC), либо поменять структуру документа (например, разрешить вставлять оглавление не в начало документа, а где-то посередине) или выполнить нестандартную (пользовательскую) обработку вашего документа. Эту работу должен выполнять не TW , а профессиональный программист, владеющий языком XSLT и отладчиком XSL-программ. Т. е. необходимость в его изучении отпадает (но я, например, познакомился с ним ,чтобы уметь читать (понимать) XSL-тексты).
- Документы для DocBook (и DITA) имеют XML-разметку. Она не подразумевает управление форматированием документа (только чистая разметка). Для управления форматированием имеется набор инструкций XSL-FO (Formatting Objects), которые, большей частью, относятся к печатному виду документа (границы страниц верхние/нижние колонтитулы и т. п.). Если в WORDe эти параметры мы задаем с помощью диалоговых окон, то в XML- документе с помощью конструкций вида <fo: …>. Смысл этих параметров аналогичен WORD (только декларирование текстовое с учетом определенного синтаксиса). Если такие инструкции вставлены в XML- документ, то, например, конвертор в html будет их просто игнорировать (в html нет страниц и, соответственно, колонтитулов), либо вставлять соответствующие команды прямо в генерируемый html-код.
Другие же конверторы (например, в PDF) эти инструкции обрабатывают и создают промежуточный файл с расширением.fo, из которого потом создается PDF –файл. В этот промежуточный файл .fo можно вручную вносить свои правки перед получением окончательного PDF ( пример таких манипуляций приведен в теме). Промежуточный файл .fo создается заново при каждом конвертировании, поэтому, если инструкции форматирования заданы не в XML–документе, то ручную корректировку .fo файла надо будет делать перед каждым конвертированием (сизифов труд).
Таким образом, изучение XSL-FO необходимо только в том случае, если ваши потребности по качеству оформления документов выше средних.
Выводы - Технология DocBook эффективна там, где надо часто корректировать малосвязанные между собой документы с последующей конвертацией их в различные форматы.
- При конвертировании тольrо в один какой-то формат вместо DocBook лучше использовать специальное ПО.
- Технология DITA основана на DocBook. Освойте сначала её.
- Технология DITA применима при создании многообъемной документации, разрабатываемой совместно коллективом авторов и содержащей большой процент однотипных фрагментов. Она востребована только лишь в очень крупных организациях (коих не так много), либо там, где выполняются аутсорсинговые работы и технология DITA жестко задана Заказчиком. Изучение собственно технологии при правильном методическом (и организационном) подходе не требует больших умственных усилий и большого количества времени (я называл 2 недели). Реально срок увеличивается из-за отсутствия русскоязычной документации и не всегда полной (и ясной) англоязычной документации (некоторые сведения надо получать экспериментальным путем). Для освоения указанных технологий не требуется освоение языков программирования и других спецификаций (XSLT, XSL-FO). При необходимости должны привлекаться профессиональные программисты.
- Предлагаемый подход (научиться самостоятельно устанавливать и конфигурировать дистрибутив DITA, изучить языки программирования XSLT и его отладчик и т. п.) считаю в корне ошибочным (метод натурального хозяйства, когда все необходимое делалось в самом хозяйстве) давно показал свою неэффективность.
Мне могут возразить: но у нас нет штата профессионалов, которые будут устанавливать ПО, писать XSL-программы и т. п., поэтому приходится обучаться всему этому самому.
Мое мнение: если TW должен быть эникейщиком, системным программистом, XSL-программистом, верстальщиком, дизайнером и многим другим одновременно, это означает, что на разработку собственно документации у него уходит порядка 10-20% рабочего времени, т. е. это не тот объем документации, для разработки которой надо использовать DITA. В такой ситуации необходимость DITA для вас такая же, как “отставной козе барабан”.
ЗаключениеВместо того чтобы ясно указать дорогу, идя по которой человек, образно говоря, через день выберется из чащи DITA (DocBook) нам Teux - Иван Сусанин этого форума предлагают влезть в такие дебри и чащобы, что человек выберется с трудом (если вообще выберется).
И последнее.
Когда мне надо сходить за хлебом в близлежащий магазин, я иду пешком; съездить на дачу - пользуюсь авто, в отпуск – поездом или самолетом. И только если мне приспичит слетать на Луну, воспользуюсь космическим кораблем – иного варианта нет.
Здесь же предлагается во всех случаях пользоваться этим “космическим кораблем”.
Основание ? “За ним будущее”.
Это, по крайней мере, несерьезно
P. S. Тому, кто дочитал до этого места – мой respect.
чат для технических писателей в Telegram
