извините за лёгкий оффтоп, но нашёл прекрасное

Осталось ещё сами статьи переименовать так же информативно )

Всем привет.
Ищу инструмент для ведения публичной пользовательской документации по API и использованию IoT платформы. Хочется, чтобы было просто в освоении (документацию пишут программисты и дополняют манагеры), не сложно в развертывании и сама по себе онлайн документация работала у пользователей быстро.

Сейчас у нас с десяток сваггеров и ссылки на них в Confluence. Поэтому отдельной приятной фичей была бы возможность импортировать swagger-файлы и показывать актуальную документацию по API прямо на сайте с доком.

Полистав чатик и канал https://t.me/technical_writing наткнулся на MkDocs. Из альтернативных решений нашел SkyDocs и Antora (тут смущает новый для меня формат AsciiDoc).

Какие минусы и плюсы у этих инструментов? Если у вас стоял подобный выбор, расскажите пожалуйста почему выбрали тот или иной инструмент? Если есть что-то лучше всех перечисленных продуктов, тоже буду рад советам.

docs.solus.io/api — вот так?

Интерактивность как здесь необязательна. Достаточно того, чтобы девелопер опубликовал новый сваггер с новым query parameter и это изменение можно было бы через git-пайплайн подтянуть в документацию автоматически

👋

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

Это не баг, это фича

Йо, а кто пользуется LaTex'ом для работы с документацией по ГОСТу, с рамками и вот этим всем? Подскажете ресурсы по освоению? Или может быть какой-то чатик, где подскажут?

Это раз https://t.me/pro_latex

Всем ГОСТописателям рекомендую слушать выпуск «Нового подкаста» про AsciiDoc и его использование в компании КУРС. Переходите уже к нам на светлую сторону, у нас docs-as-code и печеньки.

Ссылки на все платформы: https://newpodcast2.live/podcast/vanya-and-asiidoc/

А это два ^^^

Спасибище!

Известный редактор, автор книги про текст в интерфейсе, возмущённо пишет о людях, которые путают "надеть" и "одеть", когда просят его надеть медицинскую маску. Говорят "езжайте" вместо "поезжайте" [в лифте без меня, потому что вы без маски и можете меня заразить].

А как же уважение и забота о людях? Без этого зачем вообще нужна редактура, все эти тексты?

Люди ведь важнее, чем слова.

А чем "езжайте"-то провинилось?

Не знаю, сами мы неграмотные

+
За важность людей

Редактура может быть не ради людей. Да и не в каждом лифте можно соблюдать соц.дистанцию, так что к лучшему, нечего кучковаться.

Тут скорее про расхождение позиции автора, которую он постулирует в редактуре, с тем, чего он на самом деле придерживается.