Почему мы выбрали Asciidoctor для ведения программной документации

Поташников Николай, ООО «КУРС-ИТ»

Содержание

  • История трансформации документирования в нашей компании

  • Почему не MS Word

  • Почему не DITA + Docbook

  • Почему не Markdown и не reStrucuturedText

  • Подводные камни Asciidoc(tor)

Из нашей истории документирования

Эволюция документирования платформенных решений

platform

Эволюция документирования заказных разработок

order

Трясина MS Word

  1. У всех есть

  2. Низкий порог вхождения

  3. Можно как-то быстро слепить что угодно

  4. Прекрасно реализованы функции создания шаблонов форматирования (стили, поля)

Может, пусть и будет MS Word?

Переиспользование содержания

contract ex

Эта презентация

adoc pres

Эта презентация: html

html pres

Эта презентация: pdf

pdf pres

Стандартизация

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

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

Если завтра отчет

Ошибка! Закладка не определена

Почему DITA + Docbook не вытащили нас из трясины

Кто может использовать DITA + Docbook

  • Технические писатели — готовы использовать

  • Бизнес-аналитики — можно убедить

  • Специалисты технической поддержки — сложно убедить

  • Разработчики — невозможно убедить

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

Единственный вариант, который мы рассматривали как замена MS Word — markup

Почему именно Asciidoc(tor)

Причина 1. Таблицы, таблицы, таблицы

Параметры

Баллы

0

0,5

1

1,5

2

3-4

Кариотип

Очень хороший

 — 

Хороший

 — 

Промежу­точный

Плохой и очень плохой

…​

Группа риска

Сумма баллов

Медиана общей выживаемости, мес.

Медиана времени до трансформации в ОМЛ 25% больных, мес.

Очень низкий

≤ 1,5

9,3

Не достигнута

…​

Вариант кариотипа:

Данные цитогенетического исследования

Очень хороший

  • -Y

  • del(11q)

…​

Причина 2. Все остальное

  1. Простой порог вхождения — AsciidocFX

  2. Удобная функция комбинирования элементов содержания

В настоящий момент указанные функции среди систем подготовки документации поддерживает только Asciidoc(tor)

Подводные камни

Заднее крыльцо семантической разметки

[discrete]
==== Заголовок
Текст абзаца
Заголовок

Текст абзаца

*Заголовок*

Текст абзаца

Заголовок

Текст абзаца

Проверка на этапе сборки документации

Оформление документа для печати

  • Родной экспорт в pdf только похож на настоящий

  • Экспорт в tex icon на сегодняшний момент отсутствует

  • Экспорт через xsl-fo не идеален, но хорош

Существуют требования к форматированию, которые реализовать крайне сложно

Проще всего попробовать

  1. Установите AsciidocFX

  2. Возьмите в git-репозитории https://github.com/CourseOrchestra/course-doc

    • из папки doc пример проекта

    • из папки docbook-xsl-report шаблон для создания pdf

Как со мной связаться

  1. nm@potashnikoff.net

  2. @nmpotashnikoff