Technical Writing 101 🇺🇦

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

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

#uiux #en #article

В копилку тулз для тестирования документации. На одном из недавних хакатонов забацали вот такую штучку с подключаемыми рулами и прочим баловстовм —> 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

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

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

#example #en

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

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

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

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

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

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

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

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

Куда более полезные статьи про качественную документацию прикреплены в футноутах к статье про 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

У 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

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

#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

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

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

#checklist #accessibility #en

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

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

Оглавление:

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

#accessibility #en

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

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

#article #ru

Техническое писательство иногда (исходя из моего опыта, окей если вы пишете исключительно мануалы и 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

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

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

#book #en

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

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

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

#conference #en

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

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

#language #en

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

#checklist #en