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

#tool #en #markdown #knowledgemanagement

Gatsby запустил бенчмарк willit.build, в котором можно посмотреть и даже посчитать время билда сайта с разным объемом страниц и с разных контент-провайдеров. Не зря чувакам кучу денег вдонатили, развиваются быстрее всех. Пора копать в его сторону, будет не самым бесполезным знанием в арсенале техрайтера/докопса.

#SSG #tool

Пятничного чтива пост.

Вы када-нить задумывались, как проводились и документировались исследования до того, как был изобретён LaTeX?

Очень крутецкий тред именно про это:

Тред на threader: https://threadreaderapp.com/thread/1262489387767480322.html

Оригинальный тред в Twitter'е: https://twitter.com/iraphas13/status/1262489387767480322

#LaTeX #en #article

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

Эта статья от StackOverflow о том как писать техническую спецификацию:

https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/

#article #en #resource

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

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

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

#SSG #tool #en #markdown

Есть в английском такой термин как weasel words, что на нашенском будет "обтекаемые выражения", это ни к чему не обязывающие слова, эдакая намеренная двусмысленность. Вы уже наверное поняли к чему я веду. В нашей работе не стоит злоупотреблять такими вещами (хотя иногда можно, когда хочется звучать почеловечнее, показать что вы слушаете, как на самом деле говорят "обычные люди"), всё это довольно таки серая зона, которую надо научиться чувствовать и использовать аккуратно и в меру.

Но чтобы уметь нащупывать этот момент и использовать его во благо, врага надо знать в лицо, так сказать "практиковать митридатизм".

Предлагаю к ознакомлению бессмертную классику прямиком из 1991 "Как отказаться от обтекаемых выражений" (🇺🇸)

Для упрощения жизни себе и другим, постарайтесь автоматизировать это не только в голове (да, это сложно, слишком много переменных нужно держать в уме) но и современными тулзами. В этом вам поможет или наш старый добрый правильно настроенный друг Vale или отдельно живущий write-good. И тот и другой можно настроить на проверку weasel words (и в качестве приятного бонуса можно даже включить подсказки E-Prime)

#language #en #testthedocs

Хороший пост-пища-для-размышлений на idratherbewriting.

>Почему технических писателей часто считают столь неважной частью компании?

И еще бонусный пост из комментариев (их тоже почитайте, там хорошо). О грамотном наборе компетенций для современного писателя и о том, почему "технический писатель" не самое удачное название профессии. Он предлагает "complexity translator".

Понравилось оттуда:

>Technical writing could be compared to documenting all the components of a car’s engine. You’ll write down their names and how some parts are connected to other parts. That does not mean you’re qualified to get under the hood of the car and assemble an engine with those parts. But you could work with a technical person to translate their instructions into useable directions.

P.S:
Постить статьи с idratherbewriting слегка моветон, но как показывает практика, далеко не все смотрят по сторонам и вообще что-то читают по теме. Следовательно (в)опрос, вы как, сами почитаете или вам сюда иногда набрасывать интересного?

#en #article #career

Небольшое введение в 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