Из чатика конференции Highload

МЫ сейчас делаем так - используем для редактирования https://shd101wyy.github.io/markdown-preview-enhanced/#/

Почле чего начинаем импортировать API програмнного интерфейса - если нужно Java/C#/etc или Swagger - но уже как вкрапление. Поставка идет в бинарях - по ГОСТу (как бы) - epub, pdf, doc, HTML static. На контуре CICD используем https://github.com/shd101wyy/mume как обертка над компиляторами документации.

Если нужен UML - то генерируем его на основе исходников. Вообщем документация как код 😉.

Если нужно отдать в типографию на распечатку - то высылается уже бинарь.
В качестве тестов для документации используется Spellcheck и проверку стилистики языка - "Процент воды" и т.д. Соответственно если процент воды в тексте и лексических ошибок превышает 3% сборка падает.

Из последнего что мне понравилось как сделана поставка документации - это конечно Балерина https://ballerina.io/philosophy/

У них все examples вставляются в документацию и позволяют запустится, протестироваться и сгенерировать swagger. Одновременно с этим все example участвуют как тесты на движок

Вот это найсс

Новые люди, привет. Смотрите пин и рассказывайте о себе :)

Привет. Я software developer. Ищу современные практики documentation as a code.

https://idratherbewriting.com/2017/06/02/when-docs-are-not-like-code/ 😁😁

#whois В основном пишу процессинг на Python, в последнее время еще появился проект по кредитованию.

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

Всё хотел написать про создание презентаций в логике "Документация как код" (в нашем случае, в стеке Reveal.js -- Asciidoctor) и не хватало задору. У коллеги хватило: https://habr.com/ru/post/456032/

Отличная история

Хм, я пробовал revealjs для одного из своих докладов но ощущение было "больше — никогда". Но правда мне в бимере легче и приятнее презы делать, reveal какой-то жутко неудобный. Надо будет попробовать в следующем докладе, может через asciidoctor попроще

еще вариант
https://www.swipe.to/

markdown-preview-enhanced/presentation.md at master · shd101wyy/markdown-preview-enhanced · GitHub
https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/presentation.md

Там тот же reveal

Как сделать так, чтобы документация не болела?

Мы с Семёном @factorized провели сегодня митап про документацию на Highload++ Siberia. Поговорили о типичных проблемах разработки, которые можно решать с помощью документации. Конечно, всё законспектировали. Вот, держите: https://github.com/docops-hq/conf/blob/master/highload/19/siberia/docs.md

Если вы были на митапе или вам просто интересна эта тема — давайте общаться дальше, заходите в чат @docsascode.

ох ничоси, теперь сообщения из канала дублируются в чатик сами

Балдёж

Привет и добро пожаловать )