У ребят из iFixit (сообщество людей, которые помогают друг другу что-либо починить или восстановить) есть отличный Technical Writing проект, в котором любой студент может написать/отредактировать инструкцию по ремонту и/или замене каких-то деталей в поломанном устройстве. Благое дело!

Это мог бы быть отличный источник для практики для начинающего техписателя, однако там просят войти в систему используя имэйл своего университета/школы, подозреваю, что просто нужна почта в зоне .edu. НО! Если вам таки лень искать где достать соответствующее мыло, а тяга к знаниям неугасаема, то перейдите в раздел с информацией для студентов по вот этому —> https://edu.ifixit.com/student-resources/ <— линку. Там вас научат разнице между цитированием источников и тыреньем чужого контента, научат работать с форматированием в Вики, тыкнут в самые популярные ошибки и даже выдадут Tech Writing Handbook. Вот этот самый хендбук при беглом осмотре оказался довольно годным, поэтому сэкономлю вам несколько минут и поделюсь с вами им прямо тут. Have a good day, fellas ❤️

#career #resources #book #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

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

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

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

#DocsAsCode #article #en

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

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

#article #visual #en

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

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

#visual #example #en

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

#en #resource

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

#example #video #en

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

#conference #ru

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

#versioning #en

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

#versioning #example #en

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

#versioning #en

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

#example #en

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

#markdown #tool #en

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

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

#article #en

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

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

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

#DocsAsCode #SSG #en