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

Небольшое интересное утреннее чтиво от Техписа-Интерна в Google

https://medium.com/@shrij/technical-writer-internship-at-google-d17e7f580c1b

#career #en

Статейка о UX-писателях (Product Writer), с чем их есть и чем они полезны:
https://daresay.co/2018/11/20/so-youve-got-a-product-writer-on-your-team-now-what/

#uiux #en #career

Поправил тут комикс под редакторов ;)

Рассказ о том, как документация Redis Labs переехала (начала переезжать) на docs-as-code подход и заопенсорсила документацию и что из этого вышло.
https://www.docslikecode.com/articles/moving-agile-open-source-docs/

#article #DocsAsCode #en

Когда хочется красивый статик сайтик с документацией мы обычно делаем что?
1. Идем смотреть че придумали нового
2. Выбираем уже полюбившееся

Для тех, кто только находится в поиске, предлагаю зайти на https://staticsitegenerators.net/ где представлен список из 464 Static Site Generator'ов

#tool #SSG #en