Сорри, что так редко выходит какой-то ориджынал контент, совсем нет времени, но вот вам (довольно небрежный, если уж совсем на чистоту, но суть ясна) мой перевод статьи Тома Престона-Вернера, со-основателя 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

Выдержка из очень полезного треда на 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

#article #en

Держите подборку гугловских стайгайдов, посмотрите как взрослые дяди делают (C++ Style Guide, Objective-C Style Guide, Java Style Guide, Python Style Guide, R Style Guide, Shell Style Guide, HTML/CSS Style Guide, JavaScript Style Guide, AngularJS Style Guide, Common Lisp Style Guide, and Vimscript Style Guide)

https://google.github.io/styleguide/

#styleguide #en

>Познание, Дизайн и Юзабилити: Пособие для технических коммуникаторов

Неплохой такой вебинар, для общего развития, ловите:

https://www.single-sourcing.com/events/cognition-design-and-usability-an-primer-for-technical-communicators/

#video #en

Рас уж тут собрались не только любители Markdown, а еще и фанаты AsciiDoc, не могу не поделиться прекрасным сайтогенератором, как раз для вас (если вы вдруг упустили его из виду):

[0] https://antora.org/

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

[1] https://matthewsetter.com/antoras-three-core-concepts/

#asciidoc #SSG

iTunes Terms & Conditions: The Graphic Novel https://itunestandc.tumblr.com/ https://www.drawnandquarterly.com/terms-and-conditions

#visual #book #en