Комплексный инструмент технической документации

Фон

Стремление к унификации технической документации, объединению компьютерного и пользовательского контента с использованием инструментов с открытым исходным кодом. Цель состоит в том, чтобы написать (или сгенерировать) контент в выходном независимом формате файла, который затем преобразуется в окончательный документ. Рисунок ниже помогает проиллюстрировать, как соединяются общие части.

Архитектура документации

Решение должно быть независимым от операционной системы.

Выходные характеристики

Итоговый документ должен включать:

  • Столы
  • Цифры
  • Фрагменты кода
  • Подписи с автоматической нумерацией (для таблиц, рисунков и фрагментов кода)
  • Перекрестные ссылки (гиперссылки на таблицы, рисунки и библиографические ссылки)
  • Заголовки (до семи уровней; 1., 1.1., ..., 1.1.1.1.1.1.1.)
  • Приложения (до семи уровней; А., А.1, ..., А.1.1.1.1.1.1.)
  • Автонумерация заголовков и приложений
  • Содержание (с гиперссылкой)
  • Список таблиц (с гиперссылкой)
  • Список рисунков (гиперссылка)
  • Библиография (книги, статьи, журналы, технические документы, веб-сайты [с гиперссылками])
    • Разнообразие форматов (APA, Chicago, IEEE и т. д.)

Самое главное, должна быть возможна стилизация (с помощью шаблонов или кодирования), чтобы всю документацию можно было воссоздать заново с новым внешним видом. ConTeXt , например, отлично справляется с этим.

Markdown и Pandoc предлагают большую часть этой функциональности, хотя я не уверен, что они поддерживают перекрестные ссылки, автозаголовки, библиографии и фрагменты кода.

Входные функции

  • Междокументные переменные (например, имя сервера документируется один раз, но на него ссылаются архитектура приложений и спецификации требований к программному обеспечению).
  • Браузерный редактор WYSIWYG (возможно, Confluence)
    • Редактор таблиц
    • Включение (встроенные выдержки, чтобы помочь с контентом из одного источника)
    • Совместная (в идеале, в режиме реального времени)
    • Редакции
    • Markdown (возможность просмотра исходного кода, но преимущественно используется как современный текстовый процессор)
  • Компьютерный контент преобразуется в формат Markdown:
    • Документация по исходному коду (описания пакетов, гиперссылки не требуются); Javadocs, Doxygen и т. д.
    • SNMP (имена и IP-адреса сетевых устройств)
    • Диаграммы (сущности-отношения, UML, GraphViz и т. д.)
      • В идеале можно было бы импортировать изображения JPG, PNG и SVG.
    • Список суррогатных ключей и описаний базы данных (выгружен из базы данных)

Вопросы

Возможно ли вообще создать высококачественный технический документ, включающий такое большое разнообразие артефактов, используя только Markdown в качестве исходного контента?

Вот части, по которым я был бы признателен за рекомендации или предложения:

  • Включая исходный код (например, Javadoc/Doxygen -> Markdown)
  • Возможность переформатировать различные выходные данные команд *nix в Markdown ( nmap, traceroute, ls, tree, df, вывод SNMP и т. д.); перевод можно массировать с помощью awkи sed, например.
  • Редактор WYSIWYG ( альтернативы FOSS для Confluence)
  • FOSS, который может обрабатывать выходные функции из исходного кода Markdown в желаемые выходные форматы (PDF обязательно и MS Word необязательно).
    • Если Pandoc/ConTeXt не может совершить этот подвиг, то что может?
  • Программное обеспечение и/или форматы данных (например, Markdown, YAML) для интеграции библиографий и перекрестных ссылок, чтобы генератор документов (например, ConTeXt) мог их использовать (например, RStudio ) ?

Если есть единый программный пакет, объединяющий все эти функции, я бы тоже хотел об этом узнать.

Связанный

Связанные вопросы включают:

Программного обеспечения

Характеристики

Ответы (1)

Я достаточно уверен, что немного поработав, вы могли бы написать что-то очень похожее на то, что вы описываете, используя Sphinx Docs . Единственная область, с которой у вас могут возникнуть проблемы, — это совместное редактирование в реальном времени.

  • Базовым форматом является реструктурированный текст (а не уценка), но входные данные могут быть в уценке.
  • Несколько выходных форматов
  • Несколько источников ввода, включая исходный код, вики, онлайн и т. д.
  • Может вызывать и обрабатывать несколько инструментов во время процесса сборки.
  • Кроссплатформенный
  • Открытый исходный код
  • Производит действительно хорошо выглядящую документацию
  • Все запрошенные функции вывода доступны
  • Шаблоны - Да
  • Создание документов в нескольких выходных форматах — Да
  • Подсветка синтаксиса фрагментов кода на нескольких языках благодаря Pygments.
  • Обширные перекрестные ссылки: семантическая разметка и автоматические ссылки на функции, классы, цитаты, термины глоссария и аналогичную информацию.
  • Хорошая поддержка интернационализации с использованием gettext.
  • Расширяемый и активно развивающийся.
Спасибо. Похоже, есть построитель XML, который можно использовать с ConTeXt. а также то, что выглядит как расширение конструктора ConTeXt .
В примере с приложением в номерах заголовков не используются буквы. Однако это могло быть недосмотром/неправильной настройкой движка, используемого для рендеринга PDF.
Я только что провел несколько тестов на основе docutils.sourceforge.net/docs/ref/rst/… , и они отлично работают для автоматического перечисления — даже для римских цифр.
Комплексный инструмент технической документации
СпросиСетьПолитика конфиденциальности1y, 0v