Небольшое введение в diagrams-as-a-code на примере graphviz.

https://ncona.com/2020/06/create-diagrams-with-code-using-graphviz/

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

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

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

#asciidoc #en #article

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

Я уже не раз писал о том, как избавиться от passive voice в вашей документации и почти всегда привожу один и тот же трюк (с зомби).

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

https://datayze.com/passive-voice-detector

#tool #language #testthedocs #en

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

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

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

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

#markdown #en #article

Второй пост - комбинированный:

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

- Linter (вот так просто) на Руби (eww) помогает с inclusive language: gender-coded words, use of pronouns and misused words.
- Я когда-то давно писал о нём, но раз такое дело, то есть еще и linter-alex (alexjs)(в честь гендерно-нейтрального имени Саша), который делает почти то же самое.
- Кто-то захакал Grammarly прямо в VS Code, расширение конечно же сразу снесли с стора с экстеншнами, но еще можно скачать vsix файл, установить его в ручную и поклацать

#testthedocs #vscode #ide #tool #en

Я некогда писал об 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

В далёком 2016 Airbnb поделились своей болью со скейлингом шаринга (простите) знаний и вариантами того, как это дело обуздать. В статье без откровений, но мне она нравится, подойдет как старт для тех, кто только задумался о построении системы по обмену знаниями внутри компании/команды.

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

Документация по этой системе живет тут

#knowledgemanagement #article #en #changelog #example

Набрёл на DocForge – утилиту (пре-пуш тула) которая отслеживает, не устарели ли куски кода в документации. Никакой сложной настройки, пример конфигурации на скрине выше. Насколько я понял, в данный момент всё это дело еще не доступно, но товарищи просят к ним постучаться и предлагают попользовать их свежеиспеченную разработку или забукать демо.

#tool #en #DocsAsCode

У меня сейчас проходит небольшой цикл ревью очень маленьких кусочков текста (те самые microcopy) которые я писал довольно давно. И имею сказать, что усилия, требуемые, чтобы получилось ХОРОШО несоизмеримо выше усилий, которые нужно приложить, чтобы писать обычную (конечно же читабельную) документацию.

Очень согласен с этим твитом, can relate, так сказать:

https://twitter.com/krnswry/status/1283075386495074307

#resource #en #language

Дано: посудомойка с 5 режимами.

Необходимо: понять что делает второй пункт.

#example #en #visual

Вывод: опозориться можно и в документации, состоящей из одного слова и одной картинки. Иногда (при неумении/неопытности - всегда) лучше не креативить, а писать как есть. Только узнав и научившись как делать нужно, можно начать делать так, как хочется и гнуть (ну ладно, more like подгибать) правила под себя.

Hint: чтобы посмотреть правильный ответ, нажмите на 💡

#example

Я очень люблю узнавать о чужих процессах и читать о том как их строят и вообще о внутренней кухне. Недавно подвернулся сайтец Greater Greater Washington, на котором чуваки на волонтёрской основе топят за все хорошее и против всего плохого в своем округе, улучшают район и всячески его развивают.

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

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

Это пример отличной коммуникации и knowledge sharing attitude, будьте как Greater Greater Washington!

#example #career #en

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

#API #example #resource #article #en

К вопросу о том как выпрыгнуть из цикла Нужна работа --> Для работы нужен опыт --> Для опыта нужна работа. Получить хоть какое-то портфолио для начала карьеры в техписательстве или просто помочь сообществу если есть пара свободных часов в день вполне реально.

Пару лет назад я публиковал пост с реддита, где можно было нажать на понравившийся или просто интересующий проект и начать туда контрибьютить. Так вот, пост обновился несколько месяцев назад и все проекты актуальны и готовы принимать ваши контрибьюшны!

Пост оч грамотно структурирован, а что главное - есть ссылка на "How to Contribute to Open Source for first-timers and for veterans."

#vacancy #career #en

Очень (очень!) хорошая статья от Nuclino о том, почему никто не читает документацию, почему это нормально и варианты разрешения этой ситуации. Nuclino сами занимаются разботкой софта для Обмена Знаниями, такой себе аналог Notion, поэтому они знают о чем говорят.

Статья написана просто прекрасно, еще и без запихивания рекламы своего продукта глубоко всем нам в горло.

Ключевые моментики из статьи:

- Никто не читает документацию и это ОК
- Документация нужна не чтобы её читать, а чтобы с ней консультироваться
- Не пишите документацию, только ради написания. Никому не нужен огромный, толстый, пускай и всеобъемлющий кусок текста
- Пишите документацию держа в голове то, что скорее всего, её будут искать в поиске, а не просматривать все оглавления
- Пишите небольшие кусочки документации и пользуйтесь кросс-ссылками, ссылаясь на другие, такие же небольшие кусочки док.

Бонусный трек: их же статья про ценность документации и сколько может стоить отказ от обмена знаниями.

#article #en #resource

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

- Microsoft Writing Style Guide
- Google Developer Documentation Style Guide
- Apple Style Guide
- DigitalOcean Product Documentation Style Guide
- GitHub Style Guide
- GitLab Docs Documentation Style Guide
- Mailchimp Content Style Guide
- RedHat Style Guide
- Rackspace Style Guide for Technical Content
- Splunk Style Guide

Другие полезные стайлгайды:

- Federal plain language guidelines (USA)
- IEEE Editorial Style Manual for Authors
- IBM developerWorks editorial style guide
- Online Writing Lab (OWL) at Purdue University
- Paramedic Method: A Lesson in Writing Concisely
- University of Oxford Style Guide
- The Diversity Style Guide
- Progressive’s Style Guide

#styleguide #en

Тут наше любимое! Статейка чтоб была под рукой в следующий спор