Отвлекусь на секунду от восхваления Маркдауна и напомню, что это не единственный годный язык разметки текста. Например, есть еще и Asciidoc. В статейке чувак делится своим опытом по верстке (красивой) книги пользуясь Sketch и Asciidoc. Напомню, что многие популярные издательства (O'Reilly, Manning) пользуются Asciidoc для верстки профессиональной литературы, это что-то да значит!

https://hackernoon.com/using-sketch-and-asciidoc-to-generate-a-professional-tech-book-ef5b5d8dd410

#asciidoc #article

Рас уж тут собрались не только любители Markdown, а еще и фанаты AsciiDoc, не могу не поделиться прекрасным сайтогенератором, как раз для вас (если вы вдруг упустили его из виду):

[0] https://antora.org/

Выглядит довольно перспективно и современно, если вас заинтересовало, то вот тут дополнительное чтиво, которое поясняет за 3 основных концепта всей системы:

[1] https://matthewsetter.com/antoras-three-core-concepts/

#asciidoc #SSG

Часто работаете с Asciidoc? Попробуйте пописать в AsciidocFX. Умеет предательски много, графики, pie чарты, презентации, итд. https://github.com/asciidocfx/asciidocfx/

#asciidoc #en #tool

Люблю читать всевозможные документация-рилейтед саксесс-стори. В этот раз про успешный перекат на #AsciiDoc

https://medium.marqeta.com/write-your-developer-docs-in-asciidoc-78febf2a1304

#article #en #SSG

Daily reminder о существовании такой великой вещи как Pandoc. Если вам нужно перегнать документ с буквами из одного формата в другой - лучшей вещи нет. Сегодня вспомним как переехать с .md на AsciiDoc

https://matthewsetter.com/convert-markdown-to-asciidoc-withpandoc/

#markdown #asciidoc #tool #article #en

Алсо, тут yet another переизобретатель велосипеда. 0 days since кто-то пытается изобрести ИДЕАЛЬНЫЙ язык разметки документации.

https://www.freecodecamp.org/news/we-need-a-new-document-markup-language-c22e0ec44e15/

#markdown #asciidoc #en

Знаю, что среди моих читателей есть много любителей Asciidoc.

Принёс вам подборку awesome типсов и триксов. Сохранить в закладочки и открывать по необходимости:

https://mrhaki.blogspot.com/search/label/Awesome%3AAsciidoctor

#asciidoc #en #article

Vale отлично справляется с md и adoc файлами, но что если у вас Swagger API дока, которая не хавается нативно линтером?

Vale & The OpenAPI Specification поможет разобраться именно в этом. API доки такие же доки как гайды и хау-ту, держите их в чистоте и порядке, и да будут ваши юзеры благодарны!

#asciidoc #markdown #testthedocs #en #tool

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!

JetBrains в очередной раз очень сытно тизернули фичи грядущей IDE для технических писателей Writerside.

В этот раз — в самое сердечко, показали как работает встроенное тестирование документации: валидность разметки, целостность оглавления, ссылки и референсы, отпавшие картинки.

Не так давно я усиленно начал работать с AsciiDoc и решил, в виду более фичастого плагина, попробовать вернуться на WebStorm. И имею сказать, что забираю все претензии, которые имел к нему. За последние 4 или 5 лет, сколько я им не пользовался, вебшторм и все причастное к написанию в нем документации выросло до небывалых высот. Перешел с vscode и markdown на asciidoc+antora и webstorm, и не знаю бед.

В будущем канал сменит вектор с около-markdown штуковин и тулз на, как мне кажется, более зрелый и взрослый asciidoc, это моя новая любимая игрушка.

#markdown #asciidoc #tool #en #testthedocs