Держите подборку гугловских стайгайдов, посмотрите как взрослые дяди делают (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/

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

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

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

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

[0] https://antora.org/

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

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

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

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

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

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

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

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

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

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

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

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



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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://youtu.be/t4vKPhjcMZg

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

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

Всем привет, опубликовали видеозаписи с Мини-Гипербатона, прошедшего в декабре:

- Методы оценки трудозатрат и сроков документирования (Александр Лебедев): https://events.yandex.ru/lib/talks/6821/
- Как измерить качество документации и эффективность её разработки (Светлана Каюшина, Юрий Никулин, Антон Литвинов): https://events.yandex.ru/lib/talks/6822/
- Кастомизация отчётов, или Как говорить на языке метрик без переводчика (Анастасия Агеева): https://events.yandex.ru/lib/talks/6825/

Не то, чтобы новость или что-то мега-примега полезное, но советую наблюдать за этой книгой, как выйдет — уверен, будет очень полезно и круто.
https://rosenfeldmedia.com/books/writing-for-interfaces/