История о том, как команда Azure Sphere Security Services в качестве эксперимента перекатывалась с *перекрестился* SharePoint и Microsoft Word на Markdown и Git, и что из этого вышло

TL;DR

Кто бы мог подумать, что пересесть с квадратных колёс на круглые (no pun intended) всем понравится, и как следствие: "AS3 team considers the experiment incredibly successful"

https://caitiem.com/2020/03/29/design-docs-markdown-and-git/

#DocsAsCode #markdown #articke

*вдох*
ReadMe Flavored Markdown
*выдох*

https://docs.readme.com/rdmd/docs

#tool #markdown

Yet Another Markdown IDE - Obsidian. На этот раз чуваки позиционируют себя как Базу Знаний, но без "облачных" примочек, живёт это дело поверх локальной папочки с .md файликами. Вообще такой подход мне близок, это сродни покупки игр на физических носителях, да и вообще довольно таки любопытно и фичасто.

#tool #en #markdown #knowledgemanagement

Думал видел уже все цмс-ки для статических сайтецов. А вот тут еще одна попалась на глаза.

Typemill - flat-file CMS для преимущественно текстовых сайтов: хендбуки, мануалы, документация. Есть темы, плагинчики и всё опенсорсное.

Звёзд с неба не хватает, но выглядит прилично, есть четкий роадмеп, подойдет для быстрой развертки или для небольших проектиков, если у вас нет непереносимости PHP или Vue.js.

#SSG #tool #en #markdown

MyST - Markedly Structured Text — для любителей Sphinx и Markdown и "нелюбителей" reStructuredText.

MyST позволяет писать документацию Sphinx полностью в Markdown. Этот парсер предоставляет маркдаун-эквивалент синтаксиста reStructuredText.

Главные особенности MyST:

- Парсер Markdown для Сфинкса. Вы можете написать всю документацию в Sphinx в Markdown.

- Вызов директив и ролей Sphinx из Markdown, что позволит вам расширить ваш документ с помощью расширений Sphinx.

- Расширенный синтаксис Markdown для полезных функций rST, таких как комментарии к строкам и сноски.

- Сфинкс-независимый анализатор разметки MyST, который может быть расширен для добавления новых функций в MyST.

- Надстройка над CommonMark-флейвором md. Любая разметка CommonMark (например, разметка Jupyter Notebook) изначально поддерживается парсером MyST.

Перевод корявенький, но суть, я думаю, ясна

#tool #markdown #reStructuredText #SSG

И мы снова в эфире.

Извиняемся за задержку в публикациях, вся редакция увлеченно играла в Last Of Us II 👉 👈 🙄

Пост номер один - для любителей DITA, XML и прочих аббревиатур из прошлого. Но допустим, что вы таки попали в экосистему DITA (я точно знаю, что у меня есть читатели-фанаты DITA), но не хотите выглядеть как старик, а хотите если не AsciiDoc/rST, то хотя бы Markdown, и чтоб с валидацией, линтингом и вот это вот всё.

Предлагаю вашему вниманию вебинар на тему "Oxygen Markdown Support", в котором рассказывают как сделать всё вышеперечисленное прямо в Oxygen XML Editor

#markdown #en #article

Я некогда писал об Obsidian. Это такая "база знаний", но без "облачных" примочек, живёт это дело поверх локальной папочки с .md файликами. Можно смотреть связи и всякое такое.

Недавно на глаза попалось нечто похожее под названием Foam. На этот раз всё обёрнуто в vscode и приправлено довольно популярными расширениями. Автор предупреждает, что пока всё готово примерно на ~10%. Можно залайкать и следить за релизами, авось чего и вырастет из этого

#ide #knowledgemanagement #tool #markdown

Познавательная "behind-the-scenes "-статейка от GitHub о том как они перезапускали docs.github.com и с какими проблемами сталкивались и как их решали.

https://github.blog/2020-07-02-how-we-launched-docs-github-com/

#article #markdown #DocsAsCode

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

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

#asciidoc #markdown #testthedocs #en #tool

В последнее время вижу все больше и больше пользователей и советчиков (и без того популярного) MkDocs, поэтому вот вам два гайда, которые might come in handy на старте, так сказать:

1. Getting started with Material MkDocs — установка, кастомизация, публикация и траблшутинг.
2. Deploying MkDocs with Material theme to Netlify — название говорит само за себя

#markdown #DocsAsCode #SSG

Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного yet another best-on-the-market markdown editor не выдумали). Но мы то знаем, какой редактор нужен техписателю, и нет, это не Microsoft Word, это, конечно же, VS Code.

Так вот, если вы на острие, так сказать, технологий и мейнтейните какой-то статический сайтик, вы могли заметить, что уследить за всем контентом бывает сложно, поэтому некий товарищ упростил всем нам жизнь и сделал пусть и не гейм чейнджер расширение для VS Code, но приятную мелочь, как минимум.

Front Matter — это такая себе локальная headless CMS для менеджмента ваших статических сайтиков (цитата: Hugo, Jekyll, Hexo, NextJs, Gatsby, and many more), который еще и кастомными скриптами можно расширять, лепота. Все, что дополнение умеет, можно глянуть в доках.

#tool #markdown #SSG

Продолжим марафон тулз.

Часто наблюдаю, как невольные пользователи Confluence хотят причаститься к чему-то посовременнее, и, например, линтить текст в VS Code и писать в Markdown. Но как все это дело потом впихнуть в Конфу? Копипаст это скучно и к тому же утомительно.

А хочется чего-то большего, хочется git blame, хочется не кривую и скудную нативную историю изменений Confluence, а простых человеческих пуллреквестов. А может у вас даже появлялись мысли о Continuous Integration? Fear not, теперь все это можно, некий Egor Kovetskiy уже довольно давно девелопит и регулярно обновляет прекрасную тулзу под названием Mark.

Марк позволяет делать все вышеперечисленное, для этого вам просто нужно слегка сбрызнуть ваши .md файлы html-лайк метадата хэдерами и запустить миниатюрный бинарник на Go (отдельный респект).

Почитать больше можно в официальном блогпосте 🔗Use Markdown for Confluence и в соответствующем 🔗репозитории проекта.

#tool #en #markdown

GitHub’овский Маркдаун научился в сноски

#markdown #tool #en

JetBrains запостили у себя статью, которая у меня была отложена на поделиться с вами попозже, так что here we go!

В статье автор усиленно сетует на стагнацию техрайт тулинга, на отсутствие каких-либо стандартов (да, десятки сортов markdown, asciidoc, DITA и прочие, это мы про вас), отсутствие версионности, предназначенной для документации и всякое такое (статья хорошая, советую прочесть, проникнитесь может)

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

🤔 К чему пришли в JetBrains в своей новой IDE для Техписов:

>What we’ve come up with for ourselves is a semantic XML-based markup with smart completion along with Markdown support. And you can mix the two in any proportion to stay light and still inject more complex markup if you need extra features like tabs or advanced code blocks.

🔗 Читать: Better docs, less pain: the case for new docs-as-code standards

#ide #en #markdown #article

Обновилось годное дополнение для Google Docs: Docs to Markdown.

Как можно понять из названия, позволяет в пару взмахов пальцами конвертировать вашу гугл-доку в HTML или Markdown без особой головоморочки.

Обновление минорное, добавили возможность убрать пугающие красные ворнинги, но может кто не знал о плагинчике.

#markdown #tool #en

👅 Языки:

#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 — что-то совсем косвенно относящееся к техписательству, юморески

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

Stripe заопенсорсили Markdoc. Markdoc — это authoring система на основе Markdown, на которой работает веб-сайт документации Stripe который мы все любим и ставим в пример каждый раз когда кто-то спрашивает примеры хорошей документации.

Markdoc подходит как для обычных статических сайтиков, так и для фичастых сайтов с документацией или личных блогов.

Stripe подготовили довольно неплохую документацию, интерактивный плейграунд и несколько статеек о начале работы с Markdoc и даже о создании простого плагина.

#tool #en #markdown #SSG

После 4 лет работы, 75 альфа-версий и 22 бета-версий следующfя мажорная версия Docusaurus готова к продакшену.

Из главных новшеств:
- Поддержка MDX: позволяет интегрировать интерактивные React компоненты прямо в документации. Пример
- Плагины: Docusaurus теперь имеет модульную архитектуру с системой плагинов. Основные функции, такие как документация, блог, страницы и поиск, работают как отдельные плагины. Доступны дополнительные плагины, например docusaurus-search-local, как замена Algolia. Больше плагинов тут
- Поддержка PWA
- Удобное версионирование документации

С более мелкими улучшениями можно ознакомиться в официальном блог посте

Читать: Announcing Docusaurus 2.0

#en #SSG #tool #markdown

Technical Writing 101

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

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

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

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

#markdown #asciidoc #tool #en #testthedocs