Technical Writing 101 🇺🇦

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

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

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

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

#metrics #en #article

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

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

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

#tool #en

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

#vintage #en

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

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

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

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

#article #en #vintage

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

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

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

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

#resource #voicetone #en

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

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

#tool

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

#book #resource

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

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

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

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

#SSG

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

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

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

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

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

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

#example

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

#uiux #tool #en

Недавно пришлось иметь дела с ZenDesk и писать в нём буквы (а точнее переносить всё из Markdown в туда) и не могу сказать, что это был приятный экспириенс. Но нашлась вот такая тулза, которой можно скормить логин инфу и API токенчик и пушить это всё прям вот как вы себе и представляете.
Делюсь — https://github.com/mbuttler/docs-tools

Будем попробовать, а пока открыл комменты к посту и если у кого-то вдруг есть варианты получше (чтобы без sigh Ruby всё было, например) — дайте знать!

P.S Любители Руби, не обижайтесь!

Хороший, годный цикл постов про дружбу Markdown + ConTeXt (типографский брат LaTeX) и Pandoc

Зачем?

Отделение текста документа от его внешнего вида (цвета, шрифты и макет) позволяет создавать единообразный фирменный стиль, упрощать сопровождение документации, упрощает совместное редактирование, встраивание всяческой CG-инфы, позволяет одновременно публиковать в нескольких форматах и повысить производительность.

1. https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/
2. https://dave.autonoma.ca/blog/2019/05/29/typesetting-markdown-part-2/
3. https://dave.autonoma.ca/blog/2019/06/16/typesetting-markdown-part-3/
4. https://dave.autonoma.ca/blog/2019/06/23/typesetting-markdown-part-4/

#visual #uiux #en #markdown

Почитайте интересный тред Продакт Менеджера docs.microsoft.com (одного из самых массивных сайтов документации, к слову)

https://twitter.com/DennisCode/status/1144108469617774592

TL;DR

Takeaways из треда:

1. Documentation is not easy.
2. Automation is key at scale.
3. Documentation is a partnership.
4. Users are part of the success equation.
5. Quantitative data without qualitative insights is not going to help you make good decisions.
6. Shared understanding can be achieved when things are written down.
7. Being attached to ideas is useless.
8. Avoid the "too many cooks" problem.
9. You will be wrong more than you will be right

#resource #article #en #career