Technical Writing 101 🇺🇦

Cтырено с хорошо начавшейся и, судя по всему, затихшей инициативы по созданию "документационного компендиума"

Awesome Technical Writing Sources:

My Tech Writing Process - Amruta Ranade
Developer to Technical Writer - r/technicalwriting
awesome-github-templates - devspace
makeareadme - dguo
What nobody tells you about documentation - Daniele Procida
3 Essential Components of Great Documentation - Eli B
Inspiring techies to become great writers - Cameron Shorter
Technical Documentation Writing Principles - Cameron Shorter
Building Our Documentation Site on platformOS — Part 2: Content Production and Layouts - Diana Lakato
Google Developer Documentation Style Guide - Google
README Maturity Model - LappleApple
Markdown Style Guide - Ciro Santilli

#styeguide #markdown #resource #article #en

Интересный кусочек истории, IBM Jargon and General Computing Dictionary, такой себе (очень неформальный) гигантский Глоссарий от IBM, и кайфовый образец технической документации.

Написано всё очень лёгким языком, приятно поскроллить и почитать всякое, есть много забавных моментов, можно использовать как источник для своего внутреннего глоссария.

Желаю всем уметь писать так просто и понятно.

https://comlay.net/ibmjarg.pdf

#example #vintage #en

Пятничный пост в четверг.

На моей памяти это один из величайших образчиков документации, конечно же после док от ИКЕИ. Примерно такого и ждут пользователи, пишите доступно, товарищи

#example

Оч познавательная и, что немаловажно, приземлённая статья от кoманды QGIS про то, почему такой большой и полезный (опенсорс!) проект не может в документацию. 

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

Рекомендуется к прочтению и ознакомлению:

https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

P.S: Наверняка вы не прокликаете по всем ссылкам в статье, поэтому я сделал это за вас, вот самая интересная: https://thegooddocsproject.dev/

#article #example #en

Небольшая подборка гайдов o том, как создавать доступный (в плане Accessible) контент:


Google: https://developers.google.com/style/accessibility

Microsoft: https://docs.microsoft.com/en-us/style-guide/accessibility/accessibility-guidelines-requirements

IBM: https://www.ibm.com/developerworks/library/styleguidelines/index.html

Wikipedia: https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Accessibility

У Web AIM есть хорошие статьи для изучения аксессебилити в вебе в целом: https://webaim.org/

#accessibility #article #styleguide #en

В вечер пятницы немножечко про организацию рабочего пространства, а в частности тулз для писательства. Лично я -- фанат VS Code и всем его усиленно советую, т.к это ультимативный редактор с тонной плагинов и вообще, как грица one stop shop, к тому же, это один из немногих проектов на Electron, который не умервщляет ваш ноутбук (кто-то еще работает за стационарными пк?). НО! Но держать еще один инстанс Хрома не нравится примерно никому и какой-никакой, а удар по батарее и общей производительности железки всё же ощутим, но это решаемо, и решаемо довольно легко.

Нам понадобится:

1. Обыкновенный браузер (фаерфокс или хром, ведь других еще не придумали)
2. MacOS или Linux, или Windows с включенным WSL 1\2.
3. Ровно один бинарник взятый отсюда https://github.com/cdr/code-server
4. 10-20 минут жизни, в зависимости от скорости чтения

Чё в итоге?

Получаем полностью рабочий VS Code, запущенный во вкладке браузера.

Минусы:

- Каждое дополнение нужно скачать вручную из VS Code Marketplace, там есть кнопка Download, скачивается .vsix файлик, его и кормите в уже запущенную веб-версию вскода.
- Дополнение GitHub Pull Requests просит более новую версию вскода, починится с апдейтом сервера, ждём.

Плюсы:

- Ваш ноут скажет вам спасибо
- Кому не покажи вскод во вкладке - все балдеют

#vscode #ide #ru

Daily reminder о существовании такой великой вещи как Pandoc. Если вам нужно перегнать документ с буквами из одного формата в другой - лучшей вещи нет. Сегодня вспомним как переехать с .md на AsciiDoc

https://matthewsetter.com/convert-markdown-to-asciidoc-withpandoc/

#markdown #asciidoc #tool #article #en

Иногда я всё-таки применяю в работе то, про что пишу. Теперь с удвоенной силой вам советую попробовать в работе линтер прозы Vale, и настроить его в качестве CI на проекте.

#testthedocs #tool #en

Что-то давно небыло крутых примеров с docs as comics, сегодня про Docker.

Всем хорошего четверга, погнал я домой

#visual #example #en

Небольшой разбор текущего положения дел в JAMstack-мире:

https://css-tricks.com/jamstack-cmss-have-finally-grown-up/

Spoiler: всё хорошо, все c каждым годом всё больше любят всевозможные статик сайт генераторы.

#SSG #article #en

Если можете\умеете в английский на слух, тут вот неплохой подкаст на послушать по дороге домой вечерком. Ана Нельсон, техпис и создатель Dexy говорит об автоматазации тестирования док (кода в доках) и о всяком таком. Лишним не будет:

Ana Nelson: Writing Maintainable Code Documentation with Automated Tools and Transclusion

https://www.maintainable.fm/episodes/ana-nelson-writing-maintainable-code-documentation-with-automated-tools-and-transclusion

#video #testthedocs #en #article

An ultimate list of resources for technical documentation.

https://tools.doctoolhub.com/

#resource #article #SSG #tool #en

И личная мини-гордость за Дмитрия Дубилета, (нЕкогда IT директор ПриватБанка и один из основателей самого юзер-френдли банка на этом полушарии - Monobank), министра кабинета министров Украины.

Дмитрий в душе айтишник и мощнейше топит за цифровизацию всего и вся (и особенно документации) и вот сегодня он объявил о пилотном запуске программы по интеграции Google сервисов в гос.сектор. Google Docs, Spreadsheets и Forms по его мнению значительно сократят время на принятие решений и соответственно избавят от необходимости печатать бумажки и возить по ним карандашами.

Небольшой размышлений-пост о найме техрайтеров в эру DevOps:

https://opensource.com/article/19/11/hiring-technical-writers-devops

Открывал его с мыслью "о, ща про докопс почитаем-с", но псто оказался местами сомнительный, там встречается вот такие предложение:

>A movement called DocOps, out of CA (now part of Broadcom), brought together technical documentation and DevOps practices, but the original team behind the concept appears to have moved on. The effort fizzled out, but I still recommend researching it online.

И вообще докопсу уделён один абзац 🤷‍♂️

Либо русскоязычное сообществой действительно местами прогрессивнее западных коллег, либо я чего-то недопонял. (там внутри статьи всё же есть годные, пускай и старые, ссылочки)

Энивей, продуктивного денька, техписочная

#career #en #docops

Technical Writing 101 🇺🇦 pinned «Привет, техписочная! Связались тут со мной ребята, которые разрабатывают редактор для работы со сложным контентом: техническим, научным, образовательным и т.п. По ссылке ниже будет форма с вопросами по вашему повседневному техрайтерскому воркфлоу, не поленитесь…»

Привет, техписочная!

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

Если вы совсем не любите заполнять формочки, то там есть вариант просто оставить свои контактные данные и свами свяжутся, и пообщаются в формате интервью.

ФОРМА

Обнаружил тут у Hugo (тубо быстрый (like 400 страниц за секунды) статик сайт генератор на Go) на офсайте есть раздел с Showcases, в которых именитые и не очень пользователи рассказывают как они к пришли к Hugo, какие технологии пользуют и какие профиты извлекли. Если вы находитесь в поиске места, куда засунуть вашу документацию, можно полистать и слизать у кого-то весь стэк и подход, это не зазорно!

#SSG #markdown #tool #en

Yet Another UX Tips, но теперь на русском

https://vc.ru/design/92106-koroche-govorya-devyat-pravil-dlya-normalnyh-ux-tekstov

#uiux #ru #article #resource