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

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

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

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

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

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

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

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

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

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

#SSG

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

#book #resource

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

#tool

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

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

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

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

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

#resource #voicetone #en

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

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

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

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

#article #en #vintage

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

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

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

#tool #en

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

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

#metrics #en #article

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

Чувак неугомонно продолжает писать годные гайды про 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/

#visual #uiux #en #markdown

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

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

#styleguide #en #article

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

#legal

https://tldrlegal.com/ — отличный по реализации, но удручающий по смыслу сервис. На сайте собраны всемозможные software лицензии (GPL, MIT и т.д) описанные максимально простым языком, который понимают все, а не только юристы. This is how documentation should work

Часто работаешь с интерфейсами? Мож изредка делаешь опросничек-другой в помощь менеджменту? А может ты тесно завязан на продукт? Учись делать правильно и помогай тем, кто пока еще делает не до конца правильно.

Рекомендации по использованию чекбоксов и *chuckles* радиокнопок:

- Checkboxes vs. Radio Buttons

У статьи хороший финал, где объясняют, почему нужны эти гайдлайны и что это не пустой трёп и что "if you don't, you'll be taken for an amateur."

#visual #uiux #en #article #resource