AsciiDoc как стандарт для подготовки документации

    ishhi puti uluchsheniya


    Ключевым фактором для по-настоящему массового продукта является простота использования, функциональность и стоимость. Как принципиальный сторонник бесплатного ПО я являюсь давним пользователем технологии АsciiDoc и считаю, что на сегодняшний день она располагает самым большим потенциалом.


    Функциональность Markdown и даже reStructuredText ограничена, а порог входа для DocBook и DITA достаточно высок, чтобы поставить на них крест как на массовом продукте. Нужна золотая середина между функциональностью и простотой. Система документации должна быть одинаково удобна на всех этапах жизненного цикла программного продукта: проектирование, реализация, сопровождение. В идеале она должна прекрасно применяться и вне задач создания программных продуктов.


    Основной проблемой, с которой я сталкивался при подготовке документации в АsciiDoc – это отсутствие полноценного конвертера в docx (MS Word) или odt (OpenOffice/LibreOffice) для сдачи документации заказчику в этих его любимых форматах. Также эти форматы очень удобны для сравнения выходных документов.


    Об этом я написал здесь, задумался, и попробовал решить задачу.


    Мне кажется, первое (возможно даже уже и не первое) приближение получилось адекватно. Проект обеспечивает формирование так называемого plain Open Document формата (Open Document в формате xml, имеет расширение fodt). Проект легко расширяем. Позволяет изменять форматирования на уровне стилей, препроцессинга документа, а также на уровне наследования классов, отвечающих за выставление тех или иных свойств. Libre Office SDK обеспечивает функции конвертирования полученного файла в форматы docx (MS Word), pdf, odt (обычный Open Document формат). Пример конвертации также приведен в проекте.


    Есть ограничения, связанные с принципиальным различием форматов текстовых процессоров и иерархических систем разметки типа Asciidoc, Docbook, DITA, html и т.п. Но в большинстве случаев они не должны носить критический характер. Случаи, когда в списке нужно размещать таблицу, внутри которой другой список, внутри которого еще таблицу, внутри которой исходный код с примером — достаточно редки.


    Из проблем, которые также необходимо решить по развитию технологии АsciiDoc, вижу следующие:


    1. Нужен редактор, который поддерживает работу с таблицами, как с сеткой. Для Docbook и DITA таких редакторов много (например, Oxygen XML, XMLmind). Для Asciidoc всё ограничивается подсветкой синтаксиса. Конечно, поменять столбцы местами в тексте быстрее, но только если вы используете Vim. Рекомендовать это делать никак не могу
    2. Заказчик обычно рецензирует выходные документы (тот же odt или docx). Необходима возможность быстро находить исходный документ и место в нём, куда должны быть внесены правки.
    3. Поскольку Asciidoc — это язык текстовой разметки, то нужен статический анализатор кода («линтер»). Например, один перенос в Asciidoc означает продолжение абзаца. Однако в реальности в документации лучше не допускать переносов, т.к. это ведёт к ошибкам (например, забыли поставить два переноса строк перед списком и Asciidoc считает, что весь список — один большой абзац, а статический анализатор бы запретил такую конструкцию сразу ещё до сборки выходной документации).

    Буду признателен всем, кто протестирует конвертер и выскажет свои замечания и предложения.

    Средняя зарплата в IT

    120 000 ₽/мес.
    Средняя зарплата по всем IT-специализациям на основании 8 965 анкет, за 1-ое пол. 2021 года Узнать свою зарплату
    Реклама
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее

    Комментарии 6

      +1
      Asciidoc отличный продукт, по большей части в своей работе я его правда использую для составления некоторой сопуствующей документации, или быстрого описания аритектуры.
        0

        Почему сопутствующей? Что мешает основной?

          0
          Чаще всего в организациях уже имеется стандарт ведения документации, а что то изменить в уже устоявшейся системе часто бывает почти невозможно, особенно если это немецкие компании. :)
            0

            Да, тут без вариантов)

        0

        Вижу, второй пункт из списка проблем аккумулирует наше с Вами обсуждение в ранее упомянутой теме.

          0

          Интересно то, что второй пункт — свойственен всем системам подготовки документации (как основанным на XML, так и основанным на текстовой разметке). Также по этому пункту все эти системы проигрываются тому же Word'у. Действительно, куда как проще вносить изменения в конечный документ. Ну и этот пункт наиболее непонятный в реализации, хотя выглядит как реализуемый при должном продумывании

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

        Самое читаемое