Интеграция VSCode и Notion

https://github.com/frencojobs/vscode-notion
Два популярных решения для работы со знаниями наконец-то можно объединить в единой среде.

У нашего главного редактора пропал нюх, но не пропал нюх на хорошие статьи про документацию! 🥁 *badum tss* 🤡 (уже все хорошо, смотрите картинку к посту)

Сегодня статья о важности Organizational Memory, о позльзе шаблонов и о пересмотре отношения к организации документации. Товарищи из Nebo признали, что чистый Agile подход к документированию (“You should only create a document if it fulfills a clear, important and immediate goal of your overall project efforts.”) эт не совсем то, что их устраивает. Было принято решение организовать группу быстрого реагирования “Great Document-Palozza” и пеерсмотреть свой подход к хранению и накоплению инженерной документации.

Спрыгнув с Agile подхода к документированию, было решено пользоватся напутствием Том Томпсона, цитируя его статью “Why agile teams should care about documentation”: “When the engineers and writers collaborate in an iterative process, they can learn from each other and make the whole process more efficient…[Moreover,] Getting technical writers involved early is a great way to get feedback on your design. If your documentation team can't figure out a feature, your customers probably won't either.” (эту статейку тоже читните, слегка базовыве вещи говорит, но, “Повторение – мать учения”!)

Получилось у них или нет — читайте в полной версии статьи How I Learned to Stop Worrying and Love Engineering Documentation

Не болейте, это скучно 🦠

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

🎤 Начнем с более свежего, с WTD подкаста.WTD подкаста.

Я уже не раз писал выражал свою любовь к SUI (Simplified User Interfaces) и сегодня как раз про это. Они там все это дело еще хитмэпами дополнили! Что может быть лучше хитмэпов c predictive eyetracking? 👀

Подкаст про упрощенную графику в скриншотах это как раз то, что нужно посреди недели.

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

Что, если бы существовал способ создания снимков экрана, который выдерживал бы быстрые итерации разрабатываемого продукта, но при этом передавал ценный смысл вашим читателям. Сегодня к нам присоединился Антон Боллен из TechSmith, который объясняет, как мы можем это сделать, используя скриншоты с низким уровнем детализации, то есть упрощенные пользовательские интерфейсы, которые позволяют вам сосредоточить внимание пользователей только на тех элементах интерфейса, которые имеют значение.”

👀 Смотреть.Смотреть.
👂 Слушать.

Пятничной документации пост.

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

Очередной срез по IT зарплатам, пока ждем полноценного и более глобального разбора от Write The Docs, довольствуемся Украинской инфой.

Зарплати українських PM, HR, DevOps, Data Science та інших ІТ-спеціалістів — зима 2021

Но нас, конечно же, интересует информация исключительно по техписательству.

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

Видим, что мы, вместе с Digital Marketing Manager имеем высшие медианы $1200. Копирайтеры попадают в  — $900.

Но, выбрав диапазон опыта работы в 4-6 лет видим красивую цифру 1900 (которая у меня даже в экран не влезла), информация собрана с 13 анкет, что есть не очень репрезентативно, но уже что-то.

Так что ноги в руки и учимся-учимся-учимся 🧑‍🎓

👋🏻Немного мини-новостей на сегодня:

👉 Статик сайт генераторов много, а хороших, как показала практика не так уж и. Docusaurus — всегда был одним из хороших, а с релизом альфа-версии второго мажорного обновления так стало совсем хорошо и feture-parity уже вроде как стопроцентная с первой версией.

>We now recommend Docusaurus 2 as the default choice to start a new Docusaurus project and encourage v1 users to migrate to Docusaurus 2.

Посему предлагаю ознакомиться с обзором успехов Docusaurus за 2020й год

🔗Читать Docusaurus 2020 Recap

👉 Мозилла запускает Open Web Docs, инициативу по финансированию и всяческому спонсированию написания документации для таких стратегически важных ресурсов как MDN Web Docs. Цель — содержать ресурсы с документацией в активными и следить за актуальностью документации. Mozilla входит в состав Руководящего комитета OWD и помогает распределять писательский ресурс для максимальной эффективности.

🔗Почитать про анонс Open Web Docs

Добрался таки до статьи Системного Аналитика комании МойСклад про документацию, и имею сказать что она отличнейшая.

Екатерина Андреевна очень down to earth аналитик и явно понимает в том, о чем говорит.

Кратенькое изложение, что это за зверь — «документация», кому это надо, а главное очень рациональный пойнты — зачем. Годнейшие примеры и аналогии, и разбор популярной беды, когда документация не формализирована, и живет только в чьем-то занятом совсем другим уме.

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

💬 Некоторые компании начинают с первых дней, а некоторые тянут до последнего. Но начинать никогда не поздно. Через 5 лет, через 10 или 13 — главное не пытаться прятать голову в песок, когда становится заметно, что сотрудникам сложно работать и есть проблемы с пониманием системы.

🔗 Читать: «Момент, когда проектная документация нужна»

👋 Если вы вдруг знаете Екатерину, передавайте ей привет

Для новоприбывших.

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

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

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

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

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

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

Все, что у них получилось очень похоже на LanguageTool (он там частично и используется) + Vale Server, а это в очередной раз подтверждает, что все мы двигаемся в ± одном направлении и это очень даже здраво.

🔗 Читать: How we made Typerighter, the Guardian’s style guide checker

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

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

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

🌀The career-changing art of reading the docsThe career-changing art of reading the docs

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

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

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

🚀🚀🚀

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

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

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

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

🚀🚀🚀

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

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

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

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

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

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

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

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

- Authoring
- Indexing
- Screenshot production
- Proofreading
- Research

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

Дерзайте!

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

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

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

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

📍 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)

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

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

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

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

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

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

Многие (на самом деле никто, мне просто нужен был повод) у меня спрашивают "О каком таком редакторском составе ты постоянно говоришь, ты же все это пишешь один". Но все не так.

На фото вы можете увидеть моего верного напарника с которым мы вместе отправляемся в путешествие.

❤️