Мне очень нравится идея Plain English, и я планирую периодически вам об этом напоминать. Из plain ("простых") принципов Английского можно почерпнуть очень много полезного для нашей профессии, у них на сайте даже слоган: "Fighting for crystal-clear communications since 1979".

Чем это может быть полезно? Ну, например можно изучить конструкции построения приложения, брать наборы стоп-слов, которыми можно пополнить свои линтеры, чтобы они в будущем выдавали ворнинги. Можно настроить свою среду разработки так, чтобы она уведомляла вас, когда предложение становится "сложным" или же слишком длинным. Сотни профитов!

http://www.plainenglish.co.uk/how-to-write-in-plain-english.html

P.S Спешу заметить, что (по моему мнению, конечно) в современном техрайтинге одним plain English (то же самое применимо и к русскому) сыт не будешь. Можно сколь угодно "просто" и без ошибок писать, но без той самой доли "индивидуальности" документация и инструкции так и будут теми самыми бумажками, которые при покупке телефона или любой другой техники все выкидывают. Я бы хотел, чтобы документация была не только понятной, но и не унылой, как защита курсовой

#language #en

Это последний пост на тему "как начать писать, что такое техрайтинг" и вообще о каких-либо базовых вещах, связанных с написанием документации. Больше никаких вступительных курсов и базовых хендбуков, в канале достаточно информации, чтобы узнать, что это за профессия такая. Нам всем пора двигаться дальше.

Я постараюсь сконцентрироваться на более технических вещах или лингвистических. Больше про стратегии, SSG, линтеры, инклюзивность, a11y, information architecture, и намного меньше про базу.

Я уже когда-то кидал сюда этот хендбук, но уж очень он хорош в качестве введения, смело отправляйте вопрошающим "как вкатиться, что надо уметь" и всякое такое:

https://www.dozuki.com/hubfs/PDFs/Dozuki_Tech_Writing_Handbook.pdf

#career #en #SSG #accessibility

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

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

Paircast — комбинация всего вышеперечисленного, но в единой обёртке. Во время работы Paircast записывает экран, микрофон и камеру, как скринкаст.

Видеоуроки - не лучший формат для (изучения) программирования скажете вы. Видео не индексируются и там нельзя сделать там ctrl+f, нельзя копировать и вставлять. Но не всё так просто.

Под капотом у Paircast живёт git, который отслеживает изменения файлов и согласовывает их со скринкастом. Измененный код отображается как git diff'ы в markdown файле рядом с видео, там же и показана транскрипция всего, что вы говорите.

Посмотрите как это выглядит в действии на офсайте.

Проект еще в бете, но доступ можно получить постучавшись к ним в Discord.

Документация — не только буквы, но картинки и видео.

Тут недавно слили внутреннее обучающее видео прямиком из Apple. На видео учат сотрудником Apple Maps как подготовить машину с камерой к съемке, как эту съемку осуществлять и всякое такое. Не забыли даже напомнить о перекусе во время работы 🍟

Небольшой такой взгляд в закулисье knowledge sharing’a в Apple и на их внутренние тулзы. Если было интересно каково оно в гугломашинке — уверен, примерно также.

#video #example #en

Кайфовый Твиттер-тред про то, как доносить (и как разные продукты/компании это делают) изменения в продукте до конечного пользователя. В треде собрано очень много и хороших и плохих примеров:

https://twitter.com/scottkubie/status/1064981319472553985?s=20

#changelog #en #article

Spotify выпустили TechDocs, плагин для собственного (опенсорсного) дев-портала Backstage.

Там полный набор: docs-as-code, Markdown, MkDocs, простое создание GitHub ишьюсов, поддержка Slack и прочие приятности (но, конечно, если вы готовы перебраться на Backstage).

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

#tool #en

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