One stop shop по вопросам стайлгайдов, tone of vocie и accessibility (там еще очень много про брендирование, код, дизайн системы, но нам это не очень релевантно). Очень солидная подборка, дальше этого сайта можно не ходить

http://styleguides.io/

#styleguide #en

Алсо, Write the Docs проводит ежегодный опрос по зарплатам техписов, удовлетворенности профессией и всякому такому.

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

#career #en

Есть такой сайтик, зовется goodui, на этом сайте постят примеры и результаты A/B тестирования крупнейших компаний: Amazon, Netflix, Airbnb, Etsy, Google и иже с ними.

Да, сайт посвящен в основном UI-решениям и паттернам, но и для нас, техписов, можно найти в этом ценность. Помимо того, что это просто дико интересно, т.к очень много информации на сайте берется из слитых скринов внутренней кухни, мы еще можем убедиться в пользе структурирования и упорядочивания всего и вся, и немного поучиться UX-райтингу у больших дядь.


На скрине к посту, например, пример эксперимента Amazon, где *кто бы мог подумать* структурированный и разложеный по полочкам контент оказался понятнее, читабельнее и впринципе приятнее глазу, чем полотно текста, которое выглядит автоматически сгенерированным, а-ля описания в Алиэкспресс.

#uiux #en #testthedocs

Сегодня аж 2 (два!) знаменательных события!

Во первых, нас уже 🎉 т ы с я ч а 🎉, что уж очень много, как для такой относительно узкой ниши, как документация.

Я очень рад, что наша профессия из года в год становится все более востребованной и актуальной, и что вам интересно читать все, что я тут для вас пишу и нахожу. Очень радостно читать ваш позитивный фидбек в личке, это мотивирует вести этот канал и дальше! Спасибо, что вы есть 💞!

А второе событие - Ира Моторина коллега по соседнему цеху из UX-писательского канала Редач зазвала меня в подкаст и поспрашивала всякое про техническое писательство! Как получилось — судить вам. Опыта в подкастерстве у меня очень мало, я немного стесняюсь говорить ртом, но это адски увлекательно, поэтому надеюсь, что это не последний мой опыт такого рода. Ссылки будут ниже :}

#video #ru #article #career #resource

#Подкаст

Всё, с чем ты работаешь, было создано людьми и для людей

Гость выпуска — Никита Демченко, технический писатель в Valor Software. Он рассказал, что сломается в продукте без документации, почему знать код — необязательно и какие навыки нужны новичку в профессии.

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

Слушайте там, где удобно

🍏 Apple Podcasts
🤖 Google Podcasts
💛 Яндекс.Музыка
🐟 ВКонтакте
🐛 На других площадках

An Honest Review of Gatsby

Статья в которой автор(ы) Sentry (мониторинговая платформа для разработчиков) рассказывают о своем опыте переезда с Jekyll на Gatsby. Интересно посмотреть, как на действительно большом и не самом простом проекте на самом деле работает Гетсби (hint: все не так радужно, как могло казаться). Главный пойнт в том, что статик сайт генератор не должен быть настолько сложным, что работа с MDX не так простá как это пытаются показать и что GraphQL не особо-то и нужен в SSG.

Если у вас были мысли о переводе вашей документации на Gatsby, настоятельно советую ознакомиться, там и про тот же GraphQL, и про не самую полную документацию. Всё не плохо, но достаточно проблематично, чтобы смочь в это всё с наскока, а люди в Sentry уже имели опыт, но все еще столкнулись с большим количеством (не)решаемых проблем.

#SSG #en

В подкасте я упоминал про историю Технического Писательства, про вторую мировую и всякое такое. Тут можно узнать об этом всем и о многом другом поподробнее.

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

В чем суть?

Статья называется "Whatever Happened to Technical Writing", авторства Elizabeth Tebeaux, преподавателя Технического Письма с 40 летним(!) стажем.

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

Материл - бомба. Очень советую.

#book #article #career

Пост сразу и для работодателей и для техписов.

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

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

http://stcrmc.org/wordpress/?p=2968

#career #vacancy #en

Хорошие новости для пользователей oXygen XML Editor!

Начата работа по внедрению нативной поддержки Vale. Теперь следовать стайлгайдам будет проще

https://twitter.com/radu_coravu/status/1314460946417487873

#testthedocs #tool #en

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

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

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

Это видеоподкасты в двух частях и одной текстовой:

Часть 1
Часть 2
Часть 3
Текстовая версия

#DocsAsCode #en #article

Не умеешь/не привык начинать с пустого листа? Застрял после первого предложения? Попробуй заставить Машин Лернинг (GPT-2) набросать идей!

Раньше я сам иногда пользовался Talk to Transformer, но он как-то совсем не очень. А сейчас наткнулся на writeup.ai и прям небо и земля.

Если где-то есть на пощупать что-то похожее но с GPT-3 — дайте знать в комментах.

#language #ai #en

Daily Reminder:

Содержите вашу документацию “доступной” для людей с ограниченными возможностями.

Вот как раз для этого есть более-менее полный чеклист с основными штуками, про которые не стоит забывать

#accessibility #checklist #en

И почитать что там у других:

1. Небольшая выжимка из наблюдений на WriteTheDocs
2. Более подробный разбор старых статистик и немного более свежей инфы

#career #en #article

Уже доступны видео с докладами и лайтнин толками Write the Docs Prague 2020!

Отдельно почитать про что каждый из докладов можно на официальном сайте WTD.

enjoy!


1. Mikey Ariel - Introduction to Prague 2020
2. Kruno Golubić - From Graffiti Writer to Technical Writer
3. Abigail Sutherland - Organizing a Confluence hoard, or, does this page spark joy?
4. Natali Vlatko - Documenting the (Ancient) History of Your Project
5. [Lightning Talk] Kenzie Woodbridge - Affective Data Visualization (CW)
6. [Lightning Talk] Fabrizio Ferri Benedetti - Be a Salmon
7. [Lightning Talk] Wouter Veeken - "Should I move to Japan?" -- Advice for my past self
8. Paul Brown - The Baseline -- Or Technical Writing for Non Technical Readers
9. Karen Sawrey - Remote Job On boarding: Top 10 Things We Can Do Better
10. Myriam Jessier - Making documentation discoverable in search engines
11. Andrew Haynes - A Journey to Pattern Languages
12. Matt Reiner - Bake a Little Documentation Love into Your Product
13. Karissa Van Baulen - The Importance of Using Analytics and Feedback for your Documentation
14. Diana Lakatos - Helping Your Community Contribute to Developer Documentation
15. Chris Noonan - The Rocky Road to DocOps
16. Tanks Transfeld - Emulating the Teacher's Approving Nod in Teaching Material
17. [Lightning Talk] Bart Buerman - Running a conference livestream from my living room
18. [Lightning Talk] Emily Axel - Conveying Emotion Over Slack: A Tale of Two Emojis
19. [Lightning Talk] Tina Lüdtke - A quick round trip inside the brain
20. [Lightning Talk] Shweta Naresh - Technical writers or UX advocates
21. [Lightning Talk] Surya Panneer - Technical Editing Checklist
22. Jessica Valasek Estenssoro and Arthur D'Herbemont - How to be an Avante-Garde Guinea Pig
23. Joe Malin - Need Examples? Write Your Own!
24. Jen Weaver - Future-Proofing Your Support Visuals
25. Ingrid K Towey - When Wishing Still Helped... What Folklore Can Teach Us About Technical Writing

#conference #video #en #resource #article

Vale теперь и в вебе!

Теперь для того, чтобы проверить ваш текст на соответствие с стайлгайдом (пока что Microsoft, Vale, и Write Good прибиты гвоздями, но скоро можно будет пользовать свои) не нужно настраивать ни CI, ни плагин для VS Code, теперь можно просто скормить сервису вебстранчку!

Doculint

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

#testthedocs #en #tool