Хорошая, годная статья про визуальное восприятие текста и несколько разумных tips&tricks по приведению кусков кода в документации, можно читать:

https://blog.stoplight.io/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1

Редко когда бывает, чтобы два абсолютно разных человечьих увлечения, а в моем случае это комиксы и документация (согласитесь, довольно далекие друг от друга понятия), тесно пересекались в какой-то одной штуке. Бросаю всё и спешу с вами поделиться великолепным! Скот МакКлауд (автор известнейших и даже изданных на русском «Понимание комикса», «Переизобретение комикса», «Создание комикса») в своей характерной пояснительно-разъяснительной манере учит понимать уже не комиксы, а контейнеризированные приложения используя Kubernetes. Это ге ни аль но, наслаждайтесь! Там даже внизу есть окошко терминала, в котором можно потренироваться крутить-вертеть все штуки которым собственно и учит эта дока. Нужно взять и положить эту страничку в палату мер и весов как эталонный пример документации.

https://cloud.google.com/kubernetes-engine/kubernetes-comic/

Сейчас в Венгрии в рамках хакатона TestTheDocs чуваки занимаются кучей интересных тасочек, с которыми можно ознакомиться тут https://github.com/testthedocs/sprint-2018/wiki/Tasks-and-Ideas и один из интересных пойнтов это примерно все, что я описывал в своих статьях по настройке Атома для тех, кто хочет лучше, чище и структурнее писать (на английском)

1. http://telegra.ph/Pimp-My-Markdown-Part-I-04-20-2
2. http://telegra.ph/Pimp-My-Markdown-Part-II-04-20 (opensource Grammarly но лучше + тестирование документации)

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

За развитием событий можно следить тут -> https://writethedocs.slack.com в канале #testthedocs

Чтобы получить приглашение в Write The Docs Slack нужно ввести почту на http://slack.writethedocs.org/.

Вот такой вот юзер гайд в дополненной реальности https://twitter.com/mortenjust/status/1027183855692931072

Объявили даты Шестого Гипербатона https://events.yandex.ru/events/hyperbaton/22-sep-2018/

Все мы знаем про Семантическое Версионирование (RU) https://semver.org/lang/ru/ (EN) https://semver.org/, наткнулся тут на более лирическую, кхм, версию, сентиментальную и чувстввенную, так сказать. Sentimental Versioning http://sentimentalversioning.org/ — нарративная документация as is

Пример лирического версионирования Ноды, аж в сердечке колет

Еще немножко про версионирование, в этот раз предлагаю ознакомиться с календарной нумерацией релизов, ну как в Убунте https://calver.org/

Чуть позже планирую выкатить пост про плохую документацию. Вот такие инструкции это прямо плевок в лицо всем, для кого это писалось. Пожалуйста, не делайте так.

Markdeep (http://casual-effects.com/markdeep/) теперь поддерживает встраивание аудио и всяких там подкастов. Ух!

Решил поделиться парой полезных ссылочек, но вышел небольшой (достаточно большой для plaintext поста в Телегу) пост. Поэтому вот тут можно почитать один трюк, который поможет вам писать более простым языком, который сможет схавать больше людей, а ведь чем больше людей прочитает — тем вы полезнее для общества.

https://telegra.ph/O-prostote-08-29

Docs Like Code запустили отдельную страничку с инструкциями по работе с Sphinx, Jekyll, Hugo, Continious Deployment док, Автотестам док и по работе с контентом в GH репах с, опять же, документацией:

https://www.docslikecode.com/learn/

P.S Поток контента чуть снизился из-за рабочего загруза, + понемногу пилю сайт-зеркало этого канала на котором будут статьи на английском ❤️

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

https://docbook.rocks/

Такой вам daily reminder об инвалидах:

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

https://medium.com/@amyalexandraleak/should-you-use-alt-text-or-a-caption-48311e259ded


P.S Напоминаю, что в Markdown alt text задается в таком формате .

Всем здоровых глаз 👀

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

Немного оттопырю мизинчик и напомню вам о существовании Oxford Comma. Все иногда любят поспорить о её необходимости или об обратном, но мы то техрайтеры, в наших текстах не должна читаться двусмысленность, поэтому используем её примерно всегда, вот тут можно почитать/посмотреть чуть более длинный пост про это, enjoy:

https://medium.com/@kesiparker/how-to-use-the-oxford-comma-in-technical-writing-5d03bb39b966