Technical Writing 101 🇺🇦

2021-02-02 16:22:40 Постоянные читатели этого канала могли заметить, что у канала временами имеется некий уклон в сторону автоматизации проверки стиля текста.

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

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

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

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

Читать: How we made Typerighter, the Guardian’s style guide checker Открыть/Комментировать

2021-01-29 13:37:29 Для новоприбывших.

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

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

2021-01-27 18:09:51 Добрался таки до статьи Системного Аналитика комании МойСклад про документацию, и имею сказать что она отличнейшая.

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

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

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

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

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

Если вы вдруг знаете Екатерину, передавайте ей привет Открыть/Комментировать

2021-01-26 15:00:24 Немного мини-новостей на сегодня:

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

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

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

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

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

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

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

Так что ноги в руки и учимся-учимся-учимся Открыть/Комментировать

2021-01-22 18:24:15 Пятничной документации пост.

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

2021-01-20 17:44:39 Мы частично выходим на прежние обороты! Пока редакция находилась на изоляции, у нас копились годные статейки и размышления.

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

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

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

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

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

Смотреть.
Слушать. Открыть/Комментировать

2021-01-15 15:00:17 У нашего главного редактора пропал нюх, но не пропал нюх на хорошие статьи про документацию! *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

Не болейте, это скучно Открыть/Комментировать

2021-01-11 17:23:14 Интеграция VSCode и Notion

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

2021-01-05 13:57:07 Часть 3

Но самой странной идеей из всех, как мне кажется, была идея из двух незамысловатых пунктов:

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



Идей нагенерено очень много, да и тема как раз для праздников, расслабить голову. + как-никак коммуникация и вроде даже "техническая”

Нашел для вас парочку годных статей как раз про вот это вот все:

Читать на Википедии
Читнуть на Vice
Глянуть на Medium

Отдельная документалка про меняющих цвет котов Открыть/Комментировать