Просто влюбился в Purple Numbers. Это же намного круче и удобнявее простых якорей на заголовки. Тут отличный пример и немного про сами Purple Numbers.

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

https://tw-toolkit.netlify.com

Пишите инструкции для здоровых людей

Рассказывает Максим Шишов.

Большинство инструкций — это ад. Они не учат пользоваться устройством, а рассказывают, как оно может навредить пользователю. Конечно, это защита от юристов и любителей сушить котов в микроволновке. Но из-за этого нормальные люди не читают инструкции, а потом приходят скандалить в сервис.

Хорошая инструкция наглядно объясняет, как запустить устройство, настроить и заставить работать. Значит, нужно описать все функции, как они могут быть полезны, как их настроить и отключить.

Если нужно соблюдать предосторожности при работе с техникой, перечислите сначала те, которые соблюдать точно нужно. Потому что если пользователь забьет на один пункт списка, это бросит тень на все остальные — и в итоге он все равно придет в сервис.

Понятные инструкции кормят половину Ютуба. Видео «Как вставить симку в Айфон» набрало миллион просмотров. Производитель может отнять хлеб у любителей и выпускать такие видео сам. Напишите инструкцию здорового человека — вы сэкономите на сервисном обслуживании, технической поддержке и получите постоянных клиентов.

Гугол напрягся и таки выкатил новость о Docsy.

Docsy — набор специально заточенных под документацию тем для Hugo. Предлагают всё это дело под слоганом "ваш проект перерос README на гитхабе? Тогда вам к нам!"

Выглядит очень перспективно, проект активно и хорошо поддерживается как сообществом так и (пусть и неофициально, но) Гуглом

Такое нам надо!

В канале @TW_Ukraine поделились ссылкой (если ваши руки в компании дотягиваются до резюме сотрудников. Мои — да. Если у вас возникают вопросы "почему?", то вы работаете или в продуктовой компании или чего-то не улавливаете в устройстве бизнеса) на бест практисы по написанию резюме. Советы дают бывший Тех Лид гугла и чувак, успевший поработать в LinkedIn и Microsoft. Короче, можно верить.

Запустился ImportDoc, — сервис, позволяющий грамотно эмбедить контент из Google Docs прямо в вебстраничку. Никаких iframe'ов, ImportDoc наследует стиль странички, в которую это всё дело встраивается. Тут видео-демонстрация, а вот тут официальный сайт, ну и для посмотреть на деле как это все работает — CodeSandbox пример

Редакция блога ушла в недельный отпуск, не переключайтесь.

И мы снова в строю. 🎉

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

https://medium.com/gsoft-tech/technically-writing-with-empathy-220da8fff319

И если у вас, как и у меня, уже давно закончились халявные статьи на медиуме — ловите ПДФ-ку

Крутецкий текстик о документации в космосе, NASA, Apollo и вот это вот всё.

Из этого текста вы узнаете:

Кто пишет документацию для космонавтов.
Пишут ли сами космонавты документацию в космосе.
Как в перчатках в открытом космосе переворачивать странички бумажного мануала.
Есть ли в космосе место для Word.

https://heroictechwriting.com/2019/07/25/technical-writing-in-space/

И рас уж мы про NASA и техрайтинг, то очень уж долго лежит у меня этот офигеннейший раритет 81-го года. С оглавлением можно ознакомиться на втором скрине. Если будет спрос и свободное время, возможно что-то и переведу оттуда. Крайне занимательное чтиво.  https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/19810013421.pdf

Гуд ньюс эвриван!

Если вам (не)повезло работать с Confluence/JIRA, то ваша жизнь, возможно, немного упростится.

Начиная с версии 2.7.3 pandoc научился в соответствующий wiki markup https://pandoc.org/releases.html

>Кто не любит говорить о метриках документации? (Никто, вот кто.) У одного из сооснователей Write the Docs, Троя Ховарда, есть развернутая статейка в блоге, в которой он внимательно рассматривает Total Time Reading (TTR) как способ оценки успеха доки или статьи. Если метрики документации это волнующая вас тема, то обязательно стоит читнуть:

http://blog.thoward37.me/articles/techdocs-metrics-total-time-reading-(ttr)/

Когда прокачал умение работать с аудиторией до максимального уровня

Чувак неугомонно продолжает писать годные гайды про Markdown + ConTeXt.

Там уже пошли расчёты, R Markdown, CSV, YAML. Ловите 5, 6 и 7 части цикла:

https://dave.autonoma.ca/blog/2019/07/06/typesetting-markdown-part-5/
https://dave.autonoma.ca/blog/2019/07/11/typesetting-markdown-part-6/
https://dave.autonoma.ca/blog/2019/08/06/typesetting-markdown-part-7/

О важности стайлгайдов

https://twitter.com/qikipedia/status/1161578207654506498?s=19

Мне снова приходится иметь дело с различными лицензиями, договорами и контрактами, и снова я вспомнил этот дивный сервис. Хочется такое для вообще всего, пользуйтесь, любите и продавливайте идеи простоты, дружелюбности, и отказа от ненужных сложностей. Создавайте продукты, тексты с человеческим лицом, а не с бюрократической искривленной мордой.