Technical Writing 101 🇺🇦

Не всё ж нам истории с хэппи-эндами читать.

Команда техписаталей Rust - всё.

Формально она существовала до сегодня, а на деле прожила с августа 2016 по август 2018.

- Вся стандартная библиотека уже задокументирована, а новые API будут описывать разработчики.
- Книга по Rust активно мейнейнится двумя людьми
- Cargo (пакетный менеджер) документируется Cargo-тимой
- Ошибки которые стреляет компилятор описывает команда, занимающаяся (кхе) разработкой самого компилятора.

Больше деталей тут:

https://blog.rust-lang.org/inside-rust/2020/03/27/goodbye-docs-team.html

Всем чилловых выходных. (если у вас все дни еще не смазались в один длинный понедельник)

#article #en

Компания documentat.io — команда экспертов по технической документации. Они пишут руководства пользователя, документируют API, составляют хорошие ТЗ и наводят порядок во внутренних базах знаний.

У ребят сейчас открыт аттракцион невиданной щедрости: они предлагают всем желающим бесплатный аудит документации.

Покажите им ваши user manuals, документацию на API, README к вашим опенсорсным проектам, внутреннюю документацию для разработчиков, и они расскажут вам:

- Как сделать вашу документацию более понятной и полезной.
- Как переехать с неудобного инструментария (MS Word? Старые wiki?) на удобный.
- Как надо правильно готовить Confluence, чтобы его читали и не захламляли.
- Как навести порядок в массиве документации.
- Как выстроить процессы работы с документацией в условиях всеобщей удаленки.

Разумеется, перед работой будут подписаны все необходимые NDA.

Еще раз: этот аудит бесплатен!

Пишите на audit@documentat.io.

http://documentat.io/#audit

#vacancy #resource #article #en

Карантин карантином, а хорошие новости по расписанию.

Microsoft рализит свою версию Grammarly под названием Microsoft Editor. Судя по последним маркетинговым роликам, где-то в недрах MS завелся офигенный моушн дизайнер, ролик с рекламой этого Editor'a ну очень красивый.

Обещают интеграцию со всем и вся: Word, Outlook, Браузер.

В перечне фишечек такое:

- Provides suggestions to improve sentence clarity
- Suggests alternate vocabulary
- Reminds you when to use formal language
- Supports over 20 languages
- A similarity checker helps catch plagiarism or lets you quickly provide citations if you’re the one writing
- Suggest alternative punctuation
- Suggest gender-neutral and inclusive terms to reduce inherent bias in writing
- Provide information on how long it takes to read or speak your document

#testthedocs #tool #en

Я очень люблю гифки, гифки в документации это приятно, а больше гифок я люблю только приложения/сервисы которые помогают их делать.

Сегодня у нас в гостях gifcap. gifcap - полностью client-side записывалка экранов, которая сразу же делает гифку из записи. Ничего никуда ни на какие сервера не уходит, всё у вас, прямо на месте. Ну и конечно же полный опенсорц.

#visual #tool

Люди никогда не перестанут жаловаться на неуществующую спеку и недостаточную широту возможностей Markdown. Сегодня до нашего эфира донёсся новый крик на этот счёт. Тут товарищ буквально умоляет перестать писать доки на Markdown и предлагает свалить куда угодно, но подальше от всеми любимых .md файликов.

Может однажды и я решусь свалить. Из всех альтернатив, больше всего, конечно, импонирует AsciiDoc, на который этот чувак из статьи выше и возлагает надежды.

#markdown #article #en

Тут вот небольшое продолжение про WeasyPrint, про который я писал раннее. Уже и темплейтик сделали, выглядит неплохо.

#en #tool

У Microsoft очень сильный Документационный отдел, у них куча прикольных самописных плагинов для ➡️VS Code ⬅️ (тут ссылка на пак со всеми сразу.)

Так вот, к чему это я.

🎁 Сегодня M$ запустили мини-конкурс с подарочками за контрибьют в их документацию. Всего-то нужно иметь аккаунт на гитхабе и зорий техрайтинговый глаз и зареплаить на этот твит ссылкой на PR.

Контрибьютить можно в такие доки:

- 📃 Build Desktop apps - UWP, Win32, WPF, Windows Forms

- 📃Windows UI Library - Controls for UWP apps, Controls API reference

- 📃Build with Windows - Windows Subsystem for Linux (моё любимое), Python, NodeJS, Mac to Windows guide

-📃Windows Hardware Developer - Tools and Drivers

Если вы начинающий техпис, это будет отличной строчкой в вашем портфолио, дерзайте

#vscode #vacancy #en #resource

Такой вот день подкастов!

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

1. Подкаст с участием UX-писателя из Netflix. Прежде чем попасть в Нетфликс, Бен Барон успел поработать в Фейсбуке и Воцапе. В подкасте обсуждаются такие темы как:
- Каково работать в Netflix;
- Как преуспеть в UX-пистаельском деле;
- Какие проблемы возникают при проектировании, когда речь заходит об использовании слов в таком приложении, как Netflix?

https://www.writersofsiliconvalley.com/blog/2020/3/3/ux-writing-netflix-ben-barone-nugent

2. The Manuscript Podcast

Этот подкаст про писательство и разработку технологических продуктов. Каждые пару недель приходит какой-то известный технический писатель, Instructional дизайнер, UX-писатель или контент-стратег.

Читал много хороших отзывов, должно быть нескучно

https://brenobarreto.co/the-manuscript-podcast/

#video #resource #article

Пока вокруг бушует хаос, техрайтеры не перестают писать.

Очередная саексесс-JAMStack-стори, в этот раз от техписа из LINE. Чуваки перекатились с Middleman на VuePress и рассказывают о том как это было:

https://engineering.linecorp.com/en/blog/line-developers-site-from-middleman-to-vuepress/

Гийом Гомез, разработчик Rust и активный контрибьютор Servo (тот самый революционный движок для Firefox) написал заметку с советами о том, как документировать Rust-проект:

https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate

#SSG #article #en

Делюсь с вами своей самой свежей болью, которую можно было бы решить/избежать грамотным сообщением об ошибке и наняв хотя бы одного техписа/ux-писателя.

Имеем: Sony PlayStation Network, мое желание купить игру, очень агрессивная и недокументированная анти-fraud система, очевидное отсутствие техписателя.

1. Жму, значится, я кнопку "Купить и оплатить игру", получаю ошибку "при обработке заказа произошла ошибка. Попробуйте повторить позже" (капитализация и пунктуация сохранены);
2. Меняю карту оплаты на ту, на которой есть деньги;
3. По совету сообщения об ошибке пробую еще раз;
4. Получаю аналогичную ошибу;
5. Звоню в техподдержку, где мне говорят, что уже после первой попытки из пункта 1 я получил бан транзакций на 24 часа (по другим сведениям неделя и больше).

Зачем было советовать попробовать еще раз, если за это я получу бан (возможно продлённый, возможно повторный)? Почему было не уведомить о существующей, как я понял, годами системе? Почему не сказать о бане на nn недель/nn часов или хотя бы вообще о бане? Почему не добавить код ошибки к этому сообщению, когда во всей остальной системе PlayStation любая ошибка содержит в себе соответствующий код, который легчайше гуглится?

Из этого получается:

1. Очень (очень) недовольный клиент;
2. ОЧЕНЬ загруженную техподдержку, которой приходится тратить время на выслушивание моей боли, на поиск моего аккаунта, на информирование меня о моем бане;
3. Испорченный имидж компании, которая буквально из имеющейся налички может строить дома, но не в силах нанять техписателя (и, судя по постоянно отваливающейся логин форме на официальном сайте, и программиста);
4. Потерянные приколы за предзаказ игры, который заканчивается через 4 дня;
5. Потерянные 20% кэшбека в честь карантина, который заканчивается еще через несколько дней.

Так ли должны работать многомиллиардные компании с крупнейшей юзербазой игроков в мире? Не уверен.

#uiux #example #en

Закончился Season of Docs 2019, о финалистах можно почитать тут. А тут можно ознакомиться со всеми 44 успешно завершенными проектами. Отдельно хочу подметить, что по обеим ссылкам доступны отчеты о проделанной работе, крайне занимательно и познавательно!

#example #conference #en #resource

На Гитхабе завели awesome-техрайтинг список, инфы пока мало, но парочка интересных ссылочек уже есть, можно поскроллить на досуге :3

По соседству живет еще awesome-jamstack, тоже не топовейший список, но можно выцедить полезностей.

#resource #book #en #SSG

День релизов! (с опозданием)

Доношу до вашего сведения, что недавно хорошенько так обновился code-server.
code-server -- самая правильная версия VSCode, ибо под каким бы соусом не мариновали Electron приложения, оно им и останется. Тут всё иначе, вы запускаете локальный (или любой другой!) сервер и заходите на 127.0.0.1:8080 и вуа-ля, у вас больше не запущено два (ато и три, если вдруг вы зачем-то пользуетесь НЕ веб-версией слака или каким-нибудь Дискордом) инстанса хрома.

Для сравнения мемори футпринты:

```VSCode - 6 электрон-процессов ~ 1Gb of RAM usage

325.16 Mb /usr/lib/electron6/electron
316.66 Mb /usr/lib/electron6/electron
213.11 Mb /usr/lib/electron6/electron
152.18 Mb /usr/lib/electron6/electron
85.18 Mb /usr/lib/electron6/electron
17.36 Mb /usr/lib/electron6/electron
-----
1109.65 Mb

code-server - 3 code-server процесса кушают ~375Mb + 1 вкладка Хрома ~100Mb in host

148.06 Mb /usr/bin/code-server
125.86 Mb /usr/bin/code-server
101.29 Mb /usr/bin/code-server
-----
375.21 Mb

```Результат, как грица, на лицо. Замеры проводились на более старой версии, сейчас может дела даже лучше.

Кроме того, зарелизился Vale v2.1.0, в нем тоже пара новинок. Добавлена поддержка многословных исключений и raw скоупы, чтобы можно было линтить необработанную размету, такой себе улучшенный --ignore-syntax.

А объединяет эти две новости то, что весь редакторский состав этого блога последний месяц в поте лица боролся за то, чтобы две эти шикарные вещи (code-server + vale) наконец-то нормально заработали вместе.

Для полноценной работы вам нужно просто поставить самые свежие версии code-server, vale и vscode-vale.

Пользуйтесь, не болейте. ❣️

#ide #vscode #en

Ловите гист со сворачивающимися блоками в Маркдауне. Там в комментах еще всякие вариации, можно под этот дропдаун много чего прятать.

#markdown #en

Kubeflow активно опенсорсит свои процессы, в этой статье (https://medium.com/kubeflow/the-making-of-kubeflow-1-0-designing-for-stability-and-broad-market-adoption-a190358e96b6) можно найти ссылки и посмотреть как у больших дядь устроены Док-спринты и вообще поглазеть на их борды и порыться в процессах и полисях. Ну это так, для общего развития.

#uiux #en #resource #article

Алсо, тут yet another переизобретатель велосипеда. 0 days since кто-то пытается изобрести ИДЕАЛЬНЫЙ язык разметки документации.

https://www.freecodecamp.org/news/we-need-a-new-document-markup-language-c22e0ec44e15/

#markdown #asciidoc #en

Фил Девис из Tech Whirl написал небольшую рефлексивную ретроспективу об истории Техрайтинга. В ней он размышляет об истории техписательства и о том, как новые подходы можно спроецировать на старые решения и какие профиты мы с этого получим.

https://techwhirl.com/we-are-living-in-a-golden-age-of-documentation/

#article #resource #en

Дорогие писатели на английском, запомните, если слово не на слуху, не употребляется постоянно в обиходе, все ваши доказательства и тыканье в словарики со словами "гляди, есть же такое слово" никому не нужны, у нас работа не про это. Лучше два простых слова, чем одно сложное.

#example #ru #resource