Выводы

— Страницы весят очень мало. Вашим читателям это понравится, если у них медленное или нестабильное соединение.
— Сервис уважает приватность читателей и не собирает никаких данных.
— Хорошо подходит для коротких заметок и конспектов.
— Пока что не подходит для публикации кода. Будем ждать обновлений

#docops_toolkit

Публикация из AsciiDoc в PDF по ГОСТ

Компания Course сдаёт отчётную документацию в PDF со строгими требованиями к оформлению, потому что работает с банками и государственными заказчиками. При этом:

— Документацию разрабатывают в формате разметки AsciiDoc, со всеми преимуществами подхода «документация как код»: пишут в удобном редакторе, версионируют в Git, легко объединяют изменения от нескольких авторов. (Попробуйте-ка заняться этим в Word.)

— Большáя часть документации автоматически генерируется из программного кода: структура БД, описание REST API сервисов, частично ПМИ и результаты автоматизированного тестирования по ПМИ.

Как получилось совместить ГОСТ и документацию как код? Николай Поташников, автор той самой статьи про диаграммы как код в PlantUML, разработал шаблон для публикации из AsciiDoc в PDF со всеми требованиями к оформлению.

Вот исходный код и документация к шаблону: github.com/CourseOrchestra/course-doc

Николай хочет дорабатывать и улучшать этот шаблон, чтобы и другие компании могли отказаться от неудобных редакторов в пользу AsciiDoc. Нужна обратная связь. Если вы используете AsciiDoc — пожалуйста, протестируйте шаблон и напишите о результатах в чат @docsascode, либо автору на @nmpotashnikoff или nm@potashnikoff.net.

#docops_toolkit #docops_markups #docops_gost