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

https://twitter.com/e_mln_e/status/1248679254633537536

#resource #en

Гитлаб предлагает пополнить свое (ну, то есть ваше) портфолио опенсорс контрибьюшнами в документацию и предоставляет список простеньких ишшью которые хорошо бы было пофиксить.

В довесок делятся перечнем "хороших первых контрибьюшнов" в качестве образца.

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

#vacancy #resource #en

Небольшой текст с рассуждениями о том, когда лучше публиковаться (документацию), когда уже написано много, или когда написано мало, и что вообще такое "много", "достаточно", и "мало".

https://ddbeck.com/how-small-is-enough/

#resource #article #en

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

Эта статья от StackOverflow о том как писать техническую спецификацию:

https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/

#article #en #resource

У меня сейчас проходит небольшой цикл ревью очень маленьких кусочков текста (те самые microcopy) которые я писал довольно давно. И имею сказать, что усилия, требуемые, чтобы получилось ХОРОШО несоизмеримо выше усилий, которые нужно приложить, чтобы писать обычную (конечно же читабельную) документацию.

Очень согласен с этим твитом, can relate, так сказать:

https://twitter.com/krnswry/status/1283075386495074307

#resource #en #language

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

#API #example #resource #article #en

Очень (очень!) хорошая статья от Nuclino о том, почему никто не читает документацию, почему это нормально и варианты разрешения этой ситуации. Nuclino сами занимаются разботкой софта для Обмена Знаниями, такой себе аналог Notion, поэтому они знают о чем говорят.

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

Ключевые моментики из статьи:

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

Бонусный трек: их же статья про ценность документации и сколько может стоить отказ от обмена знаниями.

#article #en #resource

Сегодня аж 2 (два!) знаменательных события!

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

Я очень рад, что наша профессия из года в год становится все более востребованной и актуальной, и что вам интересно читать все, что я тут для вас пишу и нахожу. Очень радостно читать ваш позитивный фидбек в личке, это мотивирует вести этот канал и дальше! Спасибо, что вы есть 💞!

А второе событие - Ира Моторина коллега по соседнему цеху из UX-писательского канала Редач зазвала меня в подкаст и поспрашивала всякое про техническое писательство! Как получилось — судить вам. Опыта в подкастерстве у меня очень мало, я немного стесняюсь говорить ртом, но это адски увлекательно, поэтому надеюсь, что это не последний мой опыт такого рода. Ссылки будут ниже :}

#video #ru #article #career #resource

Уже доступны видео с докладами и лайтнин толками Write the Docs Prague 2020!

Отдельно почитать про что каждый из докладов можно на официальном сайте WTD.

enjoy!


1. Mikey Ariel - Introduction to Prague 2020
2. Kruno Golubić - From Graffiti Writer to Technical Writer
3. Abigail Sutherland - Organizing a Confluence hoard, or, does this page spark joy?
4. Natali Vlatko - Documenting the (Ancient) History of Your Project
5. [Lightning Talk] Kenzie Woodbridge - Affective Data Visualization (CW)
6. [Lightning Talk] Fabrizio Ferri Benedetti - Be a Salmon
7. [Lightning Talk] Wouter Veeken - "Should I move to Japan?" -- Advice for my past self
8. Paul Brown - The Baseline -- Or Technical Writing for Non Technical Readers
9. Karen Sawrey - Remote Job On boarding: Top 10 Things We Can Do Better
10. Myriam Jessier - Making documentation discoverable in search engines
11. Andrew Haynes - A Journey to Pattern Languages
12. Matt Reiner - Bake a Little Documentation Love into Your Product
13. Karissa Van Baulen - The Importance of Using Analytics and Feedback for your Documentation
14. Diana Lakatos - Helping Your Community Contribute to Developer Documentation
15. Chris Noonan - The Rocky Road to DocOps
16. Tanks Transfeld - Emulating the Teacher's Approving Nod in Teaching Material
17. [Lightning Talk] Bart Buerman - Running a conference livestream from my living room
18. [Lightning Talk] Emily Axel - Conveying Emotion Over Slack: A Tale of Two Emojis
19. [Lightning Talk] Tina Lüdtke - A quick round trip inside the brain
20. [Lightning Talk] Shweta Naresh - Technical writers or UX advocates
21. [Lightning Talk] Surya Panneer - Technical Editing Checklist
22. Jessica Valasek Estenssoro and Arthur D'Herbemont - How to be an Avante-Garde Guinea Pig
23. Joe Malin - Need Examples? Write Your Own!
24. Jen Weaver - Future-Proofing Your Support Visuals
25. Ingrid K Towey - When Wishing Still Helped... What Folklore Can Teach Us About Technical Writing

#conference #video #en #resource #article

Поговорим про развитие?

Как вы видите свое будущее? Поделитесь своими намеченными ветками прокачки.

Кто что планирует вкачивать, станете ли вы UX-писателем, вкините ли пару очков опыта в DocOps и будете двигаться в сторону автоматизации? Или вам больше по душе стать Бизнес Аналитиком, который будет собирать требования к продукту и грамотно их формулировать. Есть ли на вашей работе песпективы стать кем-то кроме писателя?

Для упрощения раздумий делюсь с вами несколькими статьями и, как по мне, довольно неплохой схемой с вариантами развития (картинка приаттачена к посту).

1. Models for Personal Growth: Career Progression for Tech Writers (презентация)

2. After Tech Writing: Where Do You Go If You Want To Move On?

Если у вас завалялись матрицы навыков или диаграммы, аналогичные той, что в шапке поста, и все это дело не под строгим NDA — поделитесь, будьте добры, комментарии открыты

#career #en #resource #article

Шаблоны документации найти непросто, а хорошие шаблоны найти почти нереально.

Поэтому особенно пристально предлагаю ознакомиться с подборкой шаблонов (в Notion) на ВСЕ случаи жизни от Air!

#example #en #resource

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

> In the end, you can’t generate documentation from code. You can generate formatting and layout, and infer some structure, but you still have to write the content. You can’t express all of the content you need in code, and you can’t write good documentation the way you write code. You should probably hire a technical writer instead.

Читать

#resource #en #article

Посыпаю голову пеплом, но только под конец 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

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

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

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

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

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

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

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

#resource #ru #article

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

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

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

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

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

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

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

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

#en #career #resource

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

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

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

О том как быть более лучшим и добрым редактором.

Open Strategy Partners рассказывают и показывают на своем примере что такое Позитивный Подход при вычитке чужих работ.

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

🔗 Читать: The Positivity Pass and Why We Do It: Empathetic and constructive editing produces consistently better results and relationships over time.

#voicetone #en #resource

Заметки о Release Notes

Релиз ноуты — неотъемлемая часть любого (опенсорсного, а по факту любого осознанного) проекта. Релиз ноуты не просто должны быть, но должны быть читабельными и полезными одновременно.

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

🔗 Читать: Writing better release notes

P.S

Мы уже не раз писали о релиз ноутах, дóроги они сердцу нашей редакции, так что предлагаю оглянуться назад:

1. The art of writing great release notes
2. Masters of Product Change: Taylor Singletary - Slack
3. Medium Release Notes: Historical record of the oft-overlooked communique known as the release note & Discord Changelogs

#changelog #en #article #resource

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

🔗 Читать: Ask HN: Any great books about technical writing?

#book #resource #career #en