Супер-современный и всячески прогрессивный UK-based банк Monzo выложил в открытый доступ просто охуительного, пардоньте, качества бренд-гайд по своему внутреннему Tone of Voice. 🗣

Там вот квинтэссенция всего того, что должен уметь каждый из нас, техрайтеров, там отлчно изложено то, как и почему они выбрали такой стиль общения, какие слова они заменяют другими, почему они используют больше глаголов и меньше существительных, и прочие интересности. Есть раздел о том, как использовать эмодзи и не облажаться, есть даже всеми-любимый трюк по избавлению от пассив войса, но вместо зомби у них пример с обезьянками 🐒

Рекомендуется к копированию, модификации и выборочному мотанию на ус их правил. Мне очень понравилось, надеюсь понравится и вам.

https://monzo.com/tone-of-voice/

#styleguide #en

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

Metadoc - это персонализированная док-платформа для разработчиков (и технических писателей). Документы могут быть сгенерированы из исходного кода (или любого источника метаданных, включая контент произвольной формы). Пользователи могут добавлять закладки и заметки, сохранять их в общих рабочих пространствах и делиться ими со своей командой. Более подробная инфа на оф. сайте https://beta.metadoc.io

#tool #en

DocBook или DITA? Положение дел на 2020й год.

https://paligo.net/blog/single-sourcing/docbook-or-dita-for-technical-writing-what-is-the-difference-in-2020/

TL;DR: Люди с большим опытом в DITA приходят к выводу, что it wasn’t worth it. There was a better way, что и требовалось доказать, да.

#tool #en

Держите до слёзок актуальный привет из 1996. Это кусок внутренней рассылки из Университета Калифорнии. Оформил вам это красиво в заметочку, печатайте, вешайте перед собой и никогда-никогда не забывайте обо всём, что написано в этой памятке. Назовём это манифестом техрайтера.

#styleguide #en #article

↓↓↓↓↓↓↓↓

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

#example #ru #resource

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

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

#article #resource #en

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

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

#markdown #asciidoc #en

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

#uiux #en #resource #article

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

#markdown #en

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

Доношу до вашего сведения, что недавно хорошенько так обновился 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

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

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

#resource #book #en #SSG

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

#example #conference #en #resource

Делюсь с вами своей самой свежей болью, которую можно было бы решить/избежать грамотным сообщением об ошибке и наняв хотя бы одного техписа/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

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

Очередная саексесс-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

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

Сам я их не очень часто слушаю, но может среди вас есть любители. 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

У 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

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

#en #tool