Technical Writing 101 🇺🇦
1.6K subscribers
244 photos
3 videos
12 files
418 links
Anything's A Documentation If You're Brave Enough

👋 @SuckMyNuts
Download Telegram
Посыпаю голову пеплом, но только под конец 2020го узнал о Nielsen Norman Group.

Кто это такие?

NN/g — исследовательская и консалтинговая UX компания, которой доверяют ведущие организации по всему миру, среди клиентов NN: Google, Visa, Verizon, Sony, eBay (хотя UX ибэя по прежнему наводит страх и ужас, но может какой-то другой их проект), National Geographic и другие мастодонты индустрии.

Основатели — Якоб Нильсен и Дон Норман, признанные во всем мире эксперты в области UX. Вместе они основали Nielsen Norman Group, элитную фирму, стремящуюся улучшить повседневный опыт использования технологий.

Дон Норман
Автор книги «Дизайн повседневных вещей», также он придумал и популяризировал термин «UX» на заре работы в Apple. Дон Норман был признан Newsweek «Guru of Workable Technology».

Якоб Нильсен
Автор юзабилити-чеклиста “10 Usability Heuristics” и один из первых поборников юзабилити-тестирования. Якоб Нильсен был признан «Guru of Usable Web Pages» газетой New York Times.

Скачать “10 Usability Heuristics” можно по ссылкам ниже, а можно и почитать. 🤓

⬇️Downloads⬇️
Jakob's 10 Usability Heuristics All Posters (ZIP)
Jakob's 10 Usability Heuristics Summary Poster (PDF)
Jakob's 10 Usability Heuristics Summary Poster, A4 Size (PDF)
Jakob's 10 Usability Heuristics Summary Poster, Letter Size (PDF)

Сегодня хочу обратить ваше внимание на 10-й пункт в чеклисте - Help and Documentation

Help and Documentation: The 10th Usability Heuristic

—————————

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

Читать.

#resource #article #en
Я уже делал много постов про комиксы, так как они очень дороги сердцам всего редакторского состава и не могу обойти стороной новый комикс-гайд. В этот раз про Bash.

Прошлые комиксы в основом были от Джулии Эванс, как и вот этот вот. Она просто мастер простого и понятного визуального изложения совсем уж сложных вещей (кубернетесы, контейнеры, сеть, HTTP, Linux)

Делюсь этим не в ключе “читайте этот гайд”, а в ключе “смотрите как можно”, и не просто можно, а можно прямо КРУТО.

Bite Size Bash!

P.S:

При покупке обратите внимание на месседж под кнопкой покупки:

>Hello! It looks like you're in Ukraine, where this zine might be expensive.
>If you need it, please use this link to get 70% off the regular price.

🧡💴

#visual #example #en
Я уже поднимал тему того, как GPT-2/3 могут помочь в нашей с вами работе. Так вот, кто-то решил возвести всё это дело в абсолют и создает специализированный сервис, который поможет найти вдохновение, и подобрать слова, когда “не идёт“. Пока что с GPT-2 и небольшим датасетом, но начало уже положено, и планы на GPT-3 уже намечены.

Алогритм берет последние написанные 40 символов, анализирует их и контекстно предлагает что писать дальше.

Похоже, скоро от писательского блока не останется и следа!

Посмотреть что там с AiToWrite

#tool #ai #en
This media is not supported in your browser
VIEW IN TELEGRAM
Посоветовавшись и оценив свою аудиторию, весь редакторский состав пришел к мнению, что нашим подписчикам итак хватает поздравлений в ругих местах, но!

🎆 Но новый год же, епта! 🎆

Учитесь новому, не стойте на месте, выходите за рамки своих “прямых обязанностей” и не бойтесь быть полезны где-то, помимо документации. Качайте креативную мышцу и всегда помните, что мы пишем не для роботов, а для людей, поэтому вкладывайте в работу душу, и другие это обязательно почувствуют 🥰.

🌲 C НАСТУПАЮЩИМ! 🌲
Часть 1: Как написать самый мощный ворнинг в мире?

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

Ядерные отходы хранятся очень, очень долго и период их полураспада может длиться сотни, тысячи, а то и десятки тысяч лет, короче — гораздо дольше, чем проживем мы с вами, и, скорее всего наш язык и наши обыденные способы коммуницирования друг с другом. А как предупредить тех, кто наткнется на хранилище с отходами, но не знает ни языка и тем более не представляет себе что такое радиация?

В отчете Sandia за 1993г рекомендовалось, чтобы любое такое сообщение содержало четыре уровня возрастающей сложности:

Уровень I: Элементарная информация: «Здесь что-то рукотворное»
Уровень II: Предостережение: «Здесь что-то рукотворное, и это опасно»
Уровень III: Базовая информация: рассказывает, что, почему, когда, где, кто и как
Уровень IV: Комплексная информация: подробные письменные записи, таблицы, рисунки, графики, карты и диаграммы

#example #vintage #en
Часть 2

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

- Это место - сообщение ... и часть системы сообщений ... обратите на это внимание!
- Для нас было важно отправить это сообщение. Мы считали себя могущественной культурой.
- Это место не почетное ... Здесь не отмечается никаких высокочтимых дел ... Здесь нет ничего ценного.
- То, что здесь было для нас опасным и отталкивающим. Это сообщение является предупреждением об опасности.
- Опасность находится в определенном месте ... она увеличивается к центру ... центр опасности здесь ... определенного размера и формы и ниже нас.
- Опасность все еще существует в ваше время, как и в наше время.
- Опасность для тела, это может убить.
- Форма опасности - это излучение энергии.
- Опасность возникает только в том случае, если вы существенно потревожите это место физически. Этого места лучше избегать и оставлять необитаемым.

#example #vintage #en
Часть 3

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

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

🙄

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

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

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

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

#example #vintage #en
Интеграция 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

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

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

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

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

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

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

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


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

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

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

#example #en
Forwarded from Нац Нац
Очередной срез по 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

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

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

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

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

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

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

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

#resource #ru #article
Для новоприбывших.

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

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

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

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

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

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

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

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

#testthedocs #en