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

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

#example #en

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

👉 Статик сайт генераторов много, а хороших, как показала практика не так уж и. 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

#SSG #article #en

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

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

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

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

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

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

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

#resource #ru #article

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

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

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

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

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

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

#testthedocs #en

👀 Приятная статейка от коллеги по цеху из 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