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

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

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

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

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

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

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

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

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

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

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

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

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

Оглавление:

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

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

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/

>Вышла версия 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/

Подборочка статей о документации:

1. О пользе документации выставленной наружу (т.е у вас не просто 100-страничная PDF-ка или может вы напрягаете своих пользователей создавать тикеты, чтобы узнать простые ответы, like it’s 2009 all over again) https://mindtouch.com/resources/public-product-documentation

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

У 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 сказать сложно.

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

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

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

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

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

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

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

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

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

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

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

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

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

Супер крутой интерактивный рассказ про то, как устроен 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

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

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

Выдержка из очень полезного треда на Hackernews на тему того, как писать (и один документ про то как их читать) и структурировать технические документы. Не со всеми еще сам ознакомился, но все выглядят достойно, можно почерпнуть пару разумных мыслей. Прикрепленный файл — архив из пяти PDF’ок, сжатый новой функцией Телеграма, не боӣтесь, без обмана!  Бонус трек — хороший толк Саймона Пейтона Джонса на ту же тему:
[0] https://www.microsoft.com/en-us/research/academic-program/write-great-research-paper/
И там в разделе other resources есть еще горстка хороших ссылок на эту тему:
[1] https://www.microsoft.com/en-us/research/academic-program/write-great-research-paper/#!other-resources