Technical Writing 101 🇺🇦

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

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

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


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

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

#accessibility #article #en

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

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

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

#DocsAsCode #SSG #en

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

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

#article #en

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

#markdown #tool #en

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

#example #en

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

#versioning #en

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

#versioning #example #en

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

#versioning #en

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

#conference #ru

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

#example #video #en

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

#en #resource

Сейчас в Венгрии в рамках хакатона 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

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

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

#visual #example #en

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

https://medium.com/@taylor_atx/writing-documentation-when-you-arent-a-technical-writer-part-one-ef08a09870d1

#article #visual #en

Покра руки доходят до написания нового ориджынал контента (а они дойдут, уже есть идея, но мало исходного материала), буду стараться накидывать вам интересного чтива. Сегодня в эфире довольно известный (в узких кругах) бложик про Docs as a Code (не путать с @docops / @docsascode в Телеграме, но тут тоже хорошо)

https://www.docslikecode.com/articles/

Всем хорошего рабочего дня 😺

#DocsAsCode #article #en

Один (одна) там технический писатель из Нью Йорка поделилась в личном блоге своим воркфлоу, с кучей ссылочек, картиночек и так далее, все как вы любите. https://amrutaranade.com/2018/03/07/my-writing-process/

Из интересного:
— Мадам пользуется методом Фейнмана для лучшего запоминания и понимания предмета о котором пишет (RU) https://lifehacker.ru/metod-fejnmana/, (EN) https://collegeinfogeek.com/feynman-technique/, вполне рабочий инструмент, можно/нужно взять на вооружение
— Структурирует заметки техникой Корнелла (RU) https://lifehacker.ru/delaem-zametki-v-bloknote-po-metodu-kornella/ (EN) https://www.youtube.com/watch?v=lsR-10piMp4
— Пользует метод пяти черновиков (EN) https://goinswriter.com/how-to-write-a-book/

#article #resources #en