Technical Writing 101 🇺🇦

Испытываю некий трепет при изучении старых документов легендарных штук. Тут максимально аналоговая документация Sonic the Hedgehog 2. Тасклист, рассчет коллизий c окружением и анимация бурления лавы.

#vintage #en

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

#checklist #en

Небольшой тизер будущей статейки. На выходе имеем SVG :3

#diagram #DocsAsCode

У Valve красивейше заредизайнился сайт и есть даже вакансия Писателя! https://www.valvesoftware.com/

#vacancy #en

И один из >ЛУЧШИХ< мануалов которые я видел на эту тему. Красиво, практично, понятно даже младенцу. Стайлгайд по написанию самых-пресамых чейнджлогов. Берите на вооружение! https://keepachangelog.com/

#changelog

Прозрачно и максимально доступно написанная (и переведенная к тому же на русский!) инструкция по Семантическому Версионированию от соучредителя GitHub https://semver.org/lang/ru/spec/v2.0.0.html

#versioning #en #ru

Там вышла новая версия Marked 2, ПРЕВЬЮВЕРА маркдауновской разметки. Пишете в Markdown в своем текстовом редакторе, а в соседнем окошке все красиво отрисовывается, экспортится, еще и темы красивые есть. К тому же, для текстовых джедаев, которые пользуются Scrivener — есть поддержка и его формата, что упрощает работу с гигантскими объемами текста. Чейгджлог тут http://marked2app.com/help/changelog.html, а качать вот тут http://marked2app.com/ (есть демо)

#markdown #en

То же самое, но на русском —> http://www.opennet.ru/opennews/art.shtml?num=48569

#examples #ru

В ядрах всех крупных ОС обнаружена опасная уязвимость, которая позволяет получить доступ к памяти ядра или перехватить контроль над системой.

Уязвимости подвержены решения следующих производителей: Apple, DragonFly BSD Project, FreeBSD Project, ядро Linux, Microsoft, Red Hat, SUSE Linux, Ubuntu, VMware, Xen.

А причиной всему знаете что? Разработчики неправильно поняли инструкции в руководствах Intel и AMD.

That’s why грамотная документация может спасти мир!

Больше информации по ссылочке: https://www.kb.cert.org/vuls/id/631579

#examples #en

Немного о грамотном подборе шрифтов для всяческой Complex Data (списки, аннотации и т.д) https://www.typography.com/blog/fonts-for-complex-data

#uiux #en

В Твиттере узрел, что есть отдельный RFC (https://ru.wikipedia.org/wiki/RFC) на использование слова MUST, SHOULD, MAY в описании тех. продуктов https://tools.ietf.org/html/rfc2119

#example #en

DNS: https://howdns.works/episodes/
HTTPS: https://howhttps.works/episodes/

Хороший, нет прекрасный, или даже охуенный пример грамотной документации. Продавец доменов DNSimple на пальцах и как для детей поясняет как работает HTTPS и DNS

#example #en

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

https://www.reddit.com/r/technicalwriting/comments/800a9a/a_list_of_open_source_projects_with_volunteer/

#resources #en

Если вы вдруг захотите слезть с Word’ов и прочих первобытых тулз и попытаетесь напрячь начальство на переход на работу с документацией как с кодом, то вот ключевые доводы которые будут полезны.

#DocsAsCode #en

Кстать, там у Яндекса в Мае в Санкт-Петербурге проходит очередной Мини-Гипербатон (конференция для техрайтеров), а большой в сентябре. Будут рассказывать про редакторы для работы с текстами и всякую DITA-фигню, рекомендую к посещению ну или как минимум посмотреть видосы с конфы:
https://yandex.ru/blog/x-plain/mini-giperbaton-pro-redaktory-dlya-raboty-s-tekstami-anons-meropriyatiya

#conference #ru

Пока пишется следующая статейка — наброшу ресурсов на почитать
1. http://www.writethedocs.org/
2. http://idratherbewriting.com/
3. https://clickhelp.co/clickhelp-technical-writing-blog/
4. https://techwhirl.com/ (так себе)
5. https://www.linkedin.com/groups/112571 — отличная и довольно активная группа в линкедине для вопросов да и просто почитать

#resources #en