Technical Writing 101 🇺🇦

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

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

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

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

#markdown #en #article

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

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

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

#tool #language #testthedocs #en

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

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

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

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

#asciidoc #en #article

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

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

Хороший пост-пища-для-размышлений на 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

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

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

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

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

#language #en #testthedocs

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

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

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

#SSG #tool #en #markdown

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

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

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

#article #en #resource

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

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

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

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

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

#LaTeX #en #article

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

#SSG #tool

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

#tool #en #markdown #knowledgemanagement

Кому html/css графиков с поддержкой Markdown?

C💚SS.css

Все графики рисуются из простейших Маркдауновых списков с помощью pandoc.

Никакого js, никаких зависимостей, один .css (или .lua) файл.

Такие вот времена настали.

#markdown #visual #tool #diagram

А ещё у Notion персональный план стал бесплатным и без ограничений на блоки. Теперь у вас ровно 0 причин не попробовать эту приятную тулзу.

Такой интересный год для Microsoft-опенсорса выдался:

- Microsoft забирает назад свои слова про опенсорс: "Microsoft was on the wrong side of history when open source exploded at the beginning of the century",
- Улучшает поддержку Linux в WSL2, позволяя запускать Linux-GUI приложения прямо в винде,
- Чинит трансляцию GPU вызовов в ядро, добавляет GPU-ускорение и DirectX (!) в WSL2,
- Выпускает нормальный (опенсорсный!) терминал.

И наконец-то про документацию:

Анонсированный в 2019 Fluid Framework представляет из себя "конструктор лего" для документов, такой себе Google Docs, если хотите. Я больше это вижу подвижкой в сторону Notion-изирования, больше никакого создания и сохранения и пересылки документов. К 2020 практически все офисные пакеты ушли от парадигмы файлов и полностью окунулись в коллективное создание всего и вся в "облаке". Так вот, теперь это всё опенсорсное, весь Fluid Framework с недели на неделю появится на гитхабе и предположительно там всё на TypeScript, и судя по всему, это интересный фундамет for what's to come.

Почитать больше можно тут.

#article #en

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

https://ddbeck.com/how-small-is-enough/

#resource #article #en

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

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

#tool #markdown