GitHub выкатил маленькое, но очень приятное обновление.

Теперь в *.md и *.rst README’хах автоматически генерируется оглавление из хедингов :}

#tool #article

Docusaurus 2 вышел из стадии альфы!

С объявлением о бета-версии команда еще больше уверена, что Docusaurus 2 готов к массовому внедрению!

Авторы гордо предлагают ознакомиться с галереей уже готовых сайтов на второй версии cтатик-сайто-генератора.

Что до целей беты - можно прочитать в самом анонсе.

#tool #en

В Google Docs готовится что-то крутое

https://twitter.com/GoogleWorkspace/status/1394703393600544771?s=19

#tool #en

Если вы только начали открывать для себя линтеры простого нашего с вами языка, то предлагаю к ознакомлению отличный интродакшн в Vale.

Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.

🔗 Читать: First steps with the Vale prose linter

#tool #testthedocs #en #article

Иногда нужно быстро “поиграться текстом” на уже запаблишеном материале, будь-то заголовок, подзаголовок или какая-то сноска. Что мы все делаем обычно в таком случае? Конечно же, идем в ДевТулзы браузера и ковыряем буквы там. Но, скажем честно, процесс не самый магический и завораживающий, поэтому от него хотелось бы отказаться в пользу чего-нить поудобнеé.

Наткнулся на приятный плагинчик для (извините пользователи Firefox) Chromium-based браузеров, который превращает любой текст в готовый для редактирования

Пользуйтесь на здоровье: Polishapp 💅

#tool #visual #en

Notion запустил Synced Blocks!

Вместо того, чтобы обновлять один и тот же кусок документа в миллионе мест, теперь можно создать Synced Block и ссылаться на него в любом другом месте, а изменения подтянутся :3

P.S

Ссылочка, собсно, на блогпост с историей формата, небольшим экскурсом в 60-е и ходом мысли по ходу разработки фичи

#tool #en

Давно мы что-то про тулзы не говорили (а ничего нового, кроме очередного 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

📓 В лучший линтер для прозы Vale по просьбам трудящихся завезли улучшенные метрики читабельности.

На трудность восприятия текста могут оказывать влияние следующие лингвистические особенности:

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

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

Среди новых метрик:

- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG

🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics

#testthedocs #en #tool

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

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

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

#markdown #tool #en

Свершилось! Теперь не только GitLab умеет в Mermaid-диаграммы, а и сам GitHub наконец-то созрел и заимплементил пожалуй самую удобную тулу для рисования понятных и красивых диаграмок.

🔗 Читать: Include diagrams in your Markdown files with Mermaid

#diagram #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

У New Relic довольно неплохой стайлгайд по написанию документации. Отдельно хочу обратить внимание на 5 вопросов, которые авторы стайлгайда предлагают задать себе, чтобы понять то ли ты вообще делаешь.

Следующая секция стайлгайда “Writing inclusive content” учит как не ненароком не обидеть своего читателя. Она довольно базовая, поэтому предлагаю взглянуть на отдельную статью про настройку своего линтера, которая помогает как раз находить такие узкие места в вашей документации.

Читать:
[1] New Relic Style Guide + 5 questions
[2] Reducing negative and biased language in documentation

#testthedocs #styleguide #voicetone #en #tool #language

shot-scraper — CLI тулза для для автоматического создания скриншотов веб-сайтов.

shot-scraper помогает автоматизировать создание свежих скринов веб-приложений (можно скринить конкретную часть приложения/сайта) для последующей интеграции в документацию, чтобы визуал не отставал от контента. Можно засунуть в CI\CD и всякое такое.

Бонусом у утилиты отличная документация и два [1]блог [2]поста которые рассказывют как всем этим пользоваться, и зачем, и как это создавалось.

#en #tool #visual #screenshot

Technical Writing 101

После 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

В Slack добавляется функционал редактирования/создания документов. Компания, принадлежащая Salesforce, объявила сегодня на своей конференции разработчиков, что она создает новую функцию под названием Canvas, которая позволит пользователям создавать и редактировать полноценные документы прямо из интерфейса Slack.

Как это выглядит и работает можно глянуть в статья на The Verge или официальном блоге компании

🔗 Читать: Your digital HQ just got better with Slack canvas

#en #tool