Такой вам daily reminder об инвалидах:

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

https://medium.com/@amyalexandraleak/should-you-use-alt-text-or-a-caption-48311e259ded


P.S Напоминаю, что в Markdown alt text задается в таком формате .

Всем здоровых глаз 👀

#accessibility #article #en

Списки — это хорошо и удобно, поэтому ловите пример хорошего, годного чеклиста для проверки качества документа, может вдохновитесь и в свой воркфлоу внедрите что-то аналогичное, если вы еще не.

#checklist #en

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

https://medium.com/@kesiparker/how-to-use-the-oxford-comma-in-technical-writing-5d03bb39b966

#language #en

Совсем недавно у Write The Docs прошла конференция в Праге, если вы вдруг были не в теме или забыли или еще чего, то вот тут —> https://www.youtube.com/channel/UCr019846MitZUEhc6apDdcQ <— их канал на Ютубе, со всеми докладами за все предыдущеи годы и всякое такое.

Го умнеть вместе :3

P.S Особенно интересные доклады оттуда буду постить по мере просмотра.

#conference #en

Наткнулся тут на книжечку от ClickHelp о Техрайтинге.

Книга отлично подойдет тем, кто хочет вкатиться в специальность, покрывает такие темы как:
- В каких индустриях популярен техрайтинг?
- В чем на самом деле заключается работа техрайтера?
- Плюсы и минусы фриланса и работы в офисе.
- Что нужно знать, чтобы стать техрайтером?
- С какими трудностями сталкиваются техрайтеры в ежедневной работе.
- Всякие полезные утилиты.
- Как наладить рабочий процесс в док. команде.

#book #en

Техническое писательство иногда (исходя из моего опыта, окей если вы пишете исключительно мануалы и API-референсы, там этого практически нет) заводит в мир UX и написания текстов для “Call to Action’ов” т.н “Призывов к действию”. Копирую откуда-то определение с небольшими правками:

— Call To Action - это элемент, который подводит к логическому завершению сделки или предлагает перейти на следующий этап (какого-либо действия в пределах вашего проекта) —

Казалось бы, че там писать, одно-два слова в кнопочку, ан нет, ловите хорошие подсказки с примерами и советами как делать хорошо, а как нет:

https://medium.com/deliveroo-design/lets-do-this-how-to-write-better-calls-to-action-ea534768b599

#article #uiux #en

Сорри, что так редко выходит какой-то ориджынал контент, совсем нет времени, но вот вам (довольно небрежный, если уж совсем на чистоту, но суть ясна) мой перевод статьи Тома Престона-Вернера, со-основателя GitHub, о важности написания README в самом начале разработки (чего-либо).

https://telegra.ph/Readme-Driven-Development-09-25

#article #ru

Еще немного про инклюзивность (слепота, дислексия, новые пользователи продукта, не-нейтив спикеры) и вот это вот всё.

Гайд с подсказками как сделать жизнь вышеупомянутых групп меньшинств немножечко проще:

Оглавление:

— Как писать так, чтобы незрячие люди могли воспринимать вашу писанину с устойств для чтения с экрана;
— Как писать простым языком;
— Как подготовиться к переводу продукта;
— Как писать с оглядкой на ЦА;

#accessibility #en

Ну и чеклист по всем этим делам ;)

#checklist #accessibility #en

Cейчас в техрайтерских чатах идут бурные дискуссии по поводу тулз в которых в разных компаниях пишутся доки.

Кто про что, а я делюсь ссылкой на приятный такой обзор\разбор\общие познания о разных популярных утилитах, HAT, Wiki, Static Site Generat’орах и прочей модной штуке.

Так что если вы еще в начале пути и выбираете в чем начинать и на что переходить, милости просим. Как грит автор:

>the above should give you an idea of where to start. Unfortunately, that’s about as far as I can take you. The rest comes down to the unique characteristics of your documentation project.

Ловите http://wouter.tech/blog/choosing-a-documentation-tool/

#SSG #article #en

>Вышла версия 2.0 набора DocBook-оформления для создания электронных и печатных документов по стандарту ГОСТ 19 (ЕСПД). В новую версию вошли многочисленные улучшения и исправления соответствия стандарту ГОСТ 19, а также некоторые элементы стандарта ЕСКД (ГОСТ 2)

http://lab50.net/%D0%B5%D1%81%D0%BF%D0%B4-docbook-5-%D0%B2%D0%B5%D1%80%D1%81%D0%B8%D1%8F-2-0/

#tools #ru

О пользе документации с маркетинговой точки зрения https://document360.io/blog/untapped-power-product-documentation-marketing-saas/

#article #en

У Etsy очень интересный подход к поддержанию документации в актуальном состоянии, советую ознакомиться. Лично мне подход очень нравится концептуально, однако в качестве long-term солюшна я не вижу это удобным и растущим вширь, но что-то да можно почерпнуть:

https://codeascraft.com/2018/10/10/etsys-experiment-with-immutable-documentation/

TL;DR: Все документы делятся на два куска “why-docs” и “how-docs” и чуваки пришли к выводу, что “how-docs” меняются куда чаще и запилили слак-reactji (типа emoji) и бота, через которого можно посмотреть советы из чата тегнутые соответствующим смайликом и которые относятся к задаваемому вопросу. Красиво и современно — да, а вот насколько это удобно, долговечно и scalable сказать сложно.

#article #en

Куда более полезные статьи про качественную документацию прикреплены в футноутах к статье про Etsy, советую и их:

1. https://blog.jooq.org/2013/02/26/the-golden-rules-of-code-documentation/

2. https://hackernoon.com/write-good-documentation-6caffb9082b4

Всем продуктивного рабочего дня 🐈

#article #en

Если в вашей команде нет специалиста по написанию микротекста (интерфейсного текста), вам могут пригодиться рекомендации Райана Кордела.

1. Микротекст должен помогать пользователям справиться с их задачей. Если он не обучает, поясняет или облегчает процесс — удаляйте.

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

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

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

5. Начинайте работать с текстом на этапе первых набросков дизайна. Текст, изображения и функции должны работать на достижение общей цели.

6. Тестируйте понятность, иерархию и полезность текста: проводите исследования, узнавайте мнения людей, даже если они не совсем ваши целевые пользователи.

http://telegraf.design/6-pravil-mikrorajtinga-dlya-produktovyh-kompanij-bez-ux-kopirajtera/

Пример умной, грамотной и красивой документации. Просто о сложном.

#example #en

Супер крутой интерактивный рассказ про то, как устроен TLS (который ещё зовут SSL'ем). Разобран буквально каждый байт, переданный между клиентом и сервером.

В копилку тулз для тестирования документации. На одном из недавних хакатонов забацали вот такую штучку с подключаемыми рулами и прочим баловстовм —> https://redactor.testthedocs.org/index.html

Функционал пока скромный, но потенциал есть, но пока все еще лучше пользоваться моим решением (remark, retext + Atom):
1. https://telegra.ph/Pimp-My-Markdown-Part-I-04-20-2
2. https://telegra.ph/Pimp-My-Markdown-Part-II-04-20

#testthedocs #tool #en

Техрайтинг бывает разный, иногда, как я уже упоминал раньше, техрайтеры попадают в мир UX. Казалось бы, чё там написать одно-два слова на кнопочке, ан нет, все не так просто. Тут рассказывают почему call to action в виде кнопочки “Learn More” — дурной тон:

https://www.nngroup.com/articles/learn-more-links/

#uiux #en #article