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

Ну и чтобы вы не забывали, что техническая документация это крайне обширное понятие, которое затрагивает не только IT индустрию, предлагаю читнуть статейку про дизайн избирательных бюллетеней, чем вам не документация.

https://www.npr.org/2018/11/24/670107455/why-are-so-many-election-ballots-confusing



P.S С конца этой недели бложик вместе с администрацией уходит на двухнедельный отпуск, всем УДАЧИ ОСТАВАТЬСЯ В СВОИХ ОФИСАХ

#career #en

Метрики эффективности документации.

Совсем недавно Яндекс проводил митап про метрики эффективности документации. Были такие доклады:

— Методы оценки трудозатрат и сроков документирования или Как правильно отвечать на неправильные вопросы. Александр Лебедев, компания Философт.
— Как измерить качество документации и эффективность её разработки. Светлана Каюшина, Юрий Никулин и Антон Литвинов из Яндекса.
— Кастомизация отчётов, или Как говорить на языке метрик без переводчика. Анастасия Агеева, Intel.

Лана Новикова (@the_know_all) законспектировала доклады, там же есть ссылки на слайды:

https://gist.github.com/lananovikova10/d48191e6c8cefdd08d81e4a4a85e5cf8

Организаторы обещали выложить видеозаписи в январе 2019.

Красивые чейнджлоги всегда в почете

#changelog

При чем тут Яндекс.Авто и какой фикспрайс?

Но в целом, самый бодрый what’s new из полсотни предновогодних обновлений. #uxtext

Часто работаете с Asciidoc? Попробуйте пописать в AsciidocFX. Умеет предательски много, графики, pie чарты, презентации, итд. https://github.com/asciidocfx/asciidocfx/

#asciidoc #en #tool

Я как-то писал о митапе в Амстердаме о тестировании документации, там товарищи пилили тулзу, которая аккумулирует в себе "а collection of checks which help to improve the quality of your docs". Так вот, они время не теряли и неспешно пилили и пилили эту штуку и она доросла уже до альфы. Все это дело крутится в Докере для локальной проверки ваших текстиков, ну или можно это все запихнуть в CI. Из интересного — они впилили лучший линтер маркдауна из возможных (remark), так что есть надежда, что эта штука выстрелит, советую держать руку на пульсе. Все ссылки в раундапе за 2018-й, ознакамливайтесь!

https://testthedocs.org/roundup-12-2018.html

#testthedocs #tool #en

Небольшой (получасовой) ликбез по основным типам документации с детальным описанием каждого:

https://youtu.be/t4vKPhjcMZg

#video #en

Пример краткого и красивого Writing Guide'a от DigitalOcean:

https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines#style

#styleguide #en