👀 Приятная статейка от коллеги по цеху из Parimatch о том, как они техрайтера нанимали.

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

🔗 Читать: Как мы нанимали технического писателя

#career #vacancy #ru

🌀The career-changing art of reading the docs

☝🏼О пользе документации, но слегка в другом ключе, нежели мы, да и вы все привыкли.

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

Даже если у вас нет никаких стремлений к тому, чтобы привлечь внимание публики, очень важно быть специалистом в своей технической нише. У тех, кто проективно изучает что-то из своей сферы, отличная карьера и гарантированная работа, потому что подобные авторитетные знания крайне редки. Автор статьи приводит в пример себя. Он провел несколько лет(!), работая DBA, однако он пользовался довольно узким набором знаний и решал проблемы исключительно по мере их поступления, и никаких глобальных знаний в области SQL за несколько лет так и не обрёл.

🚀🚀🚀

Я ОЧЕНЬ согласен с этой статьей, так как периодически консультирую как знакомых технических писателей, так и тех, кто нашел меня в LinkedIn или через этот канал. Консультирую по очень разным вещам, включая те, с которыми по работе совсем не встречался, однако читал и разбирался в этом в свое свободное время. 

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

Приведу пример из последнего: Написал мне Техпис, спросил совета, ну и в итоге возникла проблема с непечатными символами в конфиге, и, как оказалось, для него концепция невидимых символов чужда. Я предложил ему лично изучить, что же это за символы такие и как они работают, на что получил ответ (дословная цитата): “Разбираться в этом не хочется. Не понятно, зачем это нужно.”

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

🚀🚀🚀

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

1️⃣ «У меня не фотографическая память. Я никогда не запомню кучу случайных документов»
2️⃣ «У меня нет времени читать кучу документации»
3️⃣ «Документы для [технологии X] никуда не годятся. Поверьте, их не стоит читать»

❓Что там за контраргументы? Читайте саму статью, она действительно стоит потраченного времени.

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

🔗Читать: The career-changing art of reading the docs

#career #article #en

LibreOffice (те, которые делают опенсорсный Microsoft Office) запустили интересную инициативу по привлечению более молодой аудитории в разработку офисного пакета. Помимо QA, маркетинга, переводов и, собственно, разработки инициатива LibreOffice New Generation предполагает также написание документации.

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

Над какими задачами предлагается работать?

- Authoring
- Indexing
- Screenshot production
- Proofreading
- Research

LibreOffice не самый скучный и неинтересный продукт, а строка в резюме и красивый бейджик в профиле на LinkedIn никогда не будут лишними.

Дерзайте!

#vacancy #en #career

Я как-то обещал про совсем уж техписную базу не писать, но сегодня исключение, зато какое! Это ультимативная точка в вопросе “как мне начать, что учить, какой курс пройти и где бы этому всему-то структурировано научиться?”

Делюсь с вами офигенным “Учебным пособием по техническому письму” под авторством Филипа Тори. Филип — преподаватель с большим стажем, ныне в отставке, от того и раздает свой учебный материал.

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

Краткое оглавление:

📍 What is – or isn’t – ‘Plain English’?
📍 Average Sentence Length?
📍 ACTIVE or PASSIVE voice – what’s the difference?
📍 Writing Style
📍 Jargon and Acronyms
📍 Instructions and Procedures
📍 Bullet Point lists and Punctuation
📍 Planning what to write
📍 Structuring your Document

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

Это 150-страничная книга с упражнениями, вопросами и ответами, предполагается, что вы ее распечатаете и будете заниматься как студенты. Я предлагаю заниматься этим в основном в первом модуле, а остальное воспринимать как теорию. Теория в книге довольно таки качественная, за исключением советов по всяким программкам и раздела про MS Word, это все-таки немного устарело и лучше бы это все не впитывать в себя. Но если вы совсем новичок, можно послушать и советов про Word.

Enjoy 🎉

⬇️ Скачать: Technical Authoring Course Training Manual (PDF)

#book #career #en

Сегодня пятница, поэтому никаких серъезных лиц, просто микро-напоминание.

🖼⬆️Примерно по этой же причине _никогда_ не используйте слово “Simple” в своей документации. Чувствуйте себя журналистами, откажитесь от субъективной оценки умений читающего 🤜🤛

#example #en

Всем приятной и ненапряжной пятницы, мы сегодня к вам с новостями.

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

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

И помните, Docs or it didn't happen!

И мы понемногу возвращаемся в рабочее русло!

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

Будем навёрстывать упущенное!

GitHub выкатил маленькое, но очень приятное обновление.

Теперь в *.md и *.rst README’хах автоматически генерируется оглавление из хедингов :}

#tool #article

Немножко похвалим себя, ну можно же? Ну хоть иногда?

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

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

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

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

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

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

🔗 Читать: Effective Technical Writing Is Essential for Your Organization’s Success

#en #career #resource

Что мы все про хард да про хард скиллы. Буду периодически подбрасывать сюда на почитать про людское, человеческое.

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

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

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

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

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

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

🔗 Читать: Who Is the Technology For?

#article #en #tonevoice

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

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

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

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

🔗 Читать: Slack’s empathy-driven approach to release notes, change management, and feature deprecations

#changelog #en #article

# Карьерные лестницы

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

И вот, волею судеб 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

#career #en #resource

Всем привет!

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

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

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

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

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

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

P.S если за последние лет 10 появился сервис в который удобно кидать ссылки на статьи, удобно это шарить с людьми и этим пользуется много народу, я готов дублировать контент и туда, дайте знать в комментариях.

*хруст пальцами*

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

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

💥 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”.

#career #en #article

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

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

🔗 Читать: How we use GitHub Actions to manage GitHub Docs

#example #knowledgemanagement

Интересный взгляд на проблему хаоса и устаревания информации в сфере ноледж шейринга через призму энтропии.

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

🔗 Читать: Entropy and knowledge management

#knowledgemanagement #en #article

Docusaurus 2 вышел из стадии альфы!

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

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

Что до целей беты - можно прочитать в самом анонсе.

#tool #en