Size: a a a

Technical Writing 101

2021 March 25
Technical Writing 101
И мы понемногу возвращаемся в рабочее русло!

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

Будем навёрстывать упущенное!
источник
2021 March 29
Technical Writing 101
GitHub выкатил маленькое, но очень приятное обновление.

Теперь в *.md и *.rst README’хах автоматически генерируется оглавление из хедингов :}
источник
2021 March 30
Technical Writing 101
Немножко похвалим себя, ну можно же? Ну хоть иногда?, ну можно же? Ну хоть иногда?

И снова о пользе нас, техписов для бизнеса.

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

Я приодически захожу в ру-чатики для техписов (часто и долго там не хватает сидеть терпения, я думаю вы понимаете о чем я) и с (не)завидным постоянством наблюдаю “угнетенных” техписателей которых заставляют писать что-то помимо документации. Эта статья предназначается именно таким людям, кто дальше своего носа не очень то и хочет что-то видеть.

А мадам в статье приводит довольно полный список мест, где мы можем пригодиться, помимо end-user док и dev-док, а это:

✔ Дизайн
✔ Тестирование
✔ Маркетинг
✔ Сейлс
и т.д

Я, конечно, понимаю, что “уметь писать” и “любить писать”, это две большие разницы, но коль мы с вами выбрали путь собирания букв в слова, а оные в предложения, так давайте покажем, чего стоит наш скилл. Чтобы не приходилось и дальше писать пояснительные статьи “Кто Такие Технические Писатели” и разъяснять людям, и бизнесу “зачем нужен техпис”.

🔗 Читать: Effective Technical Writing Is Essential for Your Organization’s Success
источник
2021 April 07
Technical Writing 101
Что мы все про хард да про хард скиллы. Буду периодически подбрасывать сюда на почитать про людское, человеческое.

🗣 Сегодня про такт.

# Кто будет этим пользоваться?
Кто будет этим пользоваться?

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

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

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

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

🔗 Читать: Who Is the Technology For?
источник
2021 April 15
Technical Writing 101
Безумно люблю чейнджлоги, отчасти из-за них я и пошел в сторону техрайтинга и вообще полюбил разбираться в комплюктерах.

Я читаю абсолютно _все_ чейнджлоги _всех_ программ и приложений, что у меня установлены и очень грущу, когда разработчики не заботятся о том, чтобы менять дефолтные чейнджлоги и оставляют там примитивные “We made some improvements”.

Одни из первых (ну или из первых, кого заметили), кто сделал из чейнджлогов отдельный развлекательный жанр — Slack, и сегодняшняя статья как раз о них.

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

🔗 Читать: Slack’s empathy-driven approach to release notes, change management, and feature deprecations
источник
2021 April 16
Technical Writing 101
# Карьерные лестницы# Карьерные лестницы

В чатах с завидной регулярностью всплывают вопросы о “прокачке” техписов. Что должен уметь Джун, Мидл и Синиор и есть ли вообще что-то там, за горизонтом синьорства?

И вот, волею судеб Sarah Drasner, VP of Developer Experience в Netlify решила заопенсорсить всевозможные карьерные лестницы, которые используются у них в организации, в том числе там есть и про нас с вами. Можно отредактировать под себя или вообще наметить себе скиллы на прокачку в будущем.

Выделили 5 уровней прокачки:

- Technical Writer I
- Technical Writer II
- Senior Technical Writer
- Staff Technical Writer
- Principal Technical Writer

Пользуйтесь, списывайте, показывайте своему начальству, модифицируйте!

🔗 Читать: Career Ladders for Technical Writers
источник
2021 April 20
Technical Writing 101
Всем привет!

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

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

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

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

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

📖 Читать меня в Pocket
📲 То же самое, но через RSS (предпочтительная опция)

P.S если за последние лет 10 появился сервис в который удобно кидать ссылки на статьи, удобно это шарить с людьми и этим пользуется много народу, я готов дублировать контент и туда, дайте знать в комментариях.
источник
2021 May 05
Technical Writing 101
*хруст пальцами*

Ну штош, приступим.

📃 Сегодня у нас небольшая подборочка накопившегося.

💥 1. Неплохой гайд под названием “The Insider’s Guide to Becoming a (Contract) Technical Writer” от автора (вроде как) хорошего курса для техписов becometechnicalwriter.com. В гайде автор проходится по всей базе того, что необходимо для контрактной работы техписателем. Гайд больше для жителей US, но большáя часть информации довольно общая, поэтому можно взглянуть одним глазком. Про всё, начиная с резюме, заканчивая наставлениями как не унывать, когда тебя морозят или пытаются нагрузить куда более большим объемом работы, чем было обговоренно зараннее.

🔗 Читать: “The Insider’s Guide to Becoming a (Contract) Technical Writer”

💥 2. Небольшой очерк на извечную тему “почему все так плохо с документацией и что с этим делать” под названием “Software makers have gotten worse at documentation and here's why that's a problem”. Никаких откровений после прочтения не будет, но напомнить себе о нашей с вами полезности лишним не будет.

🔗 Читать: “Software makers have gotten worse at documentation and here's why that's a problem”

💥 3. Заметка “Why programmers don’t write documentation” на очевидную тему но с парочкой довольно годных пойнтов (кроме того, что как бы ну.. должны писать доку мы, а не девелоперы). Заметка была ответом на совсем уж дурацкую статью “This Is Why Most Software Engineers Don’t Write Documentation”, где основным пойнтом было то, что мол нет годных тулз для документирования 🤷

🔗 Читать:“Why programmers don’t write documentation”

💥 4. Гигантский наброс от ко-фаундера и организатора Write The Docs под провокационным названием “Documentation Considered Harmful”. Весь пост проходит под слоганом “documentation may in fact be more harmful than it is helpful”. Ругается на сложность языков и оверусложненные продукты. Самый интересный материал из подборки.

🔗 Читать: “Documentation Considered Harmful”.
источник
2021 May 07
Technical Writing 101
Клёвый взгляд изнутри взгляд изнутри на то, как GitHub менеджит свои доки с помошью своих же Actions. Можно чего-нить подсмотреть и стырить себе или просто ознакомиться с концепцией Экшнсов.

Вот бы все большие компании были так же открыты как гитхабыч, приятно смотреть же!

🔗 Читать: How we use GitHub Actions to manage GitHub Docs
источник
2021 May 12
Technical Writing 101
Интересный взгляд на проблему хаоса и устаревания информации в сфере ноледж шейринга через призму энтропии.

Автор предлагает стремиться нe к утопическому “идеально”, так как это априори недостижимо, а скорее к более реальному “достаточно хорошо”. Распознание мест и моментов, когда крошечная доза порядка сейчас принесет долговременные профиты — вот путь к успеху по мнению автора.

🔗 Читать: Entropy and knowledge management
источник
Technical Writing 101
Docusaurus 2 вышел из стадии альфы!

С объявлением о бета-версии команда еще больше уверена, что Docusaurus 2 готов к массовому внедрению!

Авторы гордо предлагают ознакомиться с галереей уже готовых сайтов на второй версии cтатик-сайто-генератора.

Что до целей беты - можно прочитать в самом анонсе.
источник
2021 May 17
Technical Writing 101
👀 На просторах ЛинкедИна набрел на отличный пост Daria Shatsylo про то, почему из команды уходят техписы. ИМХО, довольно реалистичный взгляд на вещи. Как четко подметили в комментариях, можно смело брать статью и кидать своим ПМ’ам.

Предисловие:

Наличие технического писателя в команде воспринимается либо как нечто само собой разумеющееся, либо как нечто вызывающее вопросы “Ты кто? Ты что тут делаешь?”.

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

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

Почему же такой человек в один прекрасный день может взять и уйти?

🔗 Читать: Почему из команды уходит техписатель? У меня на это 5 причин

Бонус-P.S:

🔗 Читать: 14 Ways to Make a Good Technical Writer Quit
источник
2021 May 18
Technical Writing 101
В Google Docs готовится что-то крутое

https://twitter.com/GoogleWorkspace/status/1394703393600544771?s=19
источник
2021 May 26
Technical Writing 101
Всем привет!

Иксолла открыла прием заявок на направление Documentation в рамках Xsolla School 2021!

В этом году впервые организовано два потока:

– Базовый (количество участников не ограничено): для тех, кто хочет познакомиться с основными понятиями и принципами документации.

– Профильный (только 15 участников): для тех, кто уже знает основы работы с документацией и хочет прокачать профессиональные навыки.

На школе вы научитесь писать документацию, которую реально будут читать, начнете понимать особенности ГОСТов и стайлгайдов, узнаете специфику подготовки контента для UI/UX веб-приложений и многое другое!

Обучение в школе полностью бесплатное. Прочитать подробности и пройти регистрацию можно по ссылке: https://rb.gy/wftbg5
источник
2021 May 31
Technical Writing 101
Если вы только начали открывать для себя линтеры простого нашего с вами языка, то предлагаю к ознакомлению отличный интродакшн в Vale.

Объясняют и в чем отличие от линтеров кода, и этимологию самого слова, и даже делятся ссылочкой на Vale Studio, которой я совсем забыл с вами поделиться. Vale Studio это бесплатный веб-бейзд редактор, который позволяет легко создавать и тестировать новые правила. Очень тесно интегрирован с regex101.

🔗 Читать: First steps with the Vale prose linter
источник
2021 June 07
Technical Writing 101
Иногда нужно быстро “поиграться текстом” на уже запаблишеном материале, будь-то заголовок, подзаголовок или какая-то сноска. Что мы все делаем обычно в таком случае? Конечно же, идем в ДевТулзы браузера и ковыряем буквы там. Но, скажем честно, процесс не самый магический и завораживающий, поэтому от него хотелось бы отказаться в пользу чего-нить поудобнеé.

Наткнулся на приятный плагинчик для (извините пользователи Firefox) Chromium-based браузеров, который превращает любой текст в готовый для редактирования

Пользуйтесь на здоровье: Polishapp 💅
источник
2021 June 09
Technical Writing 101
🚶‍♀️ Набрёл тут на советы для пишущих от Amazon (если кто знает, где взять фулл — напишите в комментариях).

Многое уже всем знакомо, особенно если вы проходили Гугловый курс по TW, но лишним, как вы помните, повторение не бывает.

🎺 Bonus Track: 🎺

Очень детальный рассказ о структуре “Амазононовского Шестистраничника”. Это Джефф Безос невзлюбил скучные паверпойнт презентации и заставил всех писать вразумительные, легкочитаемые и усвояемые narrative- и data-driven отчеты. Ну короче, как раз то, что нам с вами нужно.

🔗 Читать: The Anatomy of an Amazon 6-pager
источник
Technical Writing 101
источник
Technical Writing 101
источник
Technical Writing 101
источник