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

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

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

Скриншоты! Как много в этом слове!

Излюбленная тема всех техрайт чатиков — обсуждать в какой тулзе они делают скрины, но это так же скучно, как слушать про чужие сны. Давайте лучше почитаем свежую статью из ISTC Communicator о том, как сделать так, чтобы снятием свежих скринов нужно было заниматься не каждый апдейт продукта. А поможет нам это сделать simplified user interface, относительно свежий подход к созданию таких себе "абстрактных" версий скриншотов интерфейса (см рис.1).

Если вам интересно почитать еще об этом, то там в конце статьи есть раздел Further Reading, а если хочется вдобавок и пообщаться про это, то для этих дел есть отдельный (англоязычный) Слак-чат

#screenshot #tool

​​Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.

Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.

Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.

Книгу можно купить на сайте издательства. Приятного чтения!

Если в PM или BA перекатываться не хочется, можно попробовать стать Скрам Мастером, somehow related

#career #en

Все мы любим Docs as a Code, но иногда этого становится мало и хочется ВСЁ as a Code, поэтому в сегодняшней подборке Презентации as a Code (с уклоном в Markdown)

Начну со своих любимых тулз:

Marp — нЕкогда Electron (не переставайте читать на этом месте) приложенька, которая кушает маркдаун и делает из них собсно презентацию, но товарищи разработчики видимо протёрли глаза и наконец поняли что Электрон — есть корень зла и свернули сие богомерзкое деяние в пользу богоподобного расширения для VS Code

Deckset — если в вашем распоряжении есть MacOS и необходимость хоть изредка делать презентации то просто жмите на ссылку и дальше не читайте. Лучшая аппка.

reveal.js — фреймворк для HTML-презентаций. Умеет вложенные солайды, Markdown ☜(ﾟヮﾟ☜), экспорт в PDF, отдельные спикер ноуты. Если впадлу что-то там мудрить, то есть онлайн-редактор. Можно закомбинить это дело с Pandoc.

remark.js — чуть более tricky, чем reveal, но дело делает. Есть подсветка кода в слайдах, нормально всё скейлится, конечно же умеет MD, отдельные спикер ноуты и всякое такое.

hackMD — это как Google Docs, но для Markdown. Тут оно за тем, что там есть режим презентаций :}

Не про Markdown, но Slides as a Code вполне себе — eagle.js — фреймворк для слайдов поверх Vue.js. Самая выпендрёжная из всех систем в списке, без лишних слов: посмотрите демки, до конца.

Notable mentions:

md2googleslides — если вы всё никак не слезете с иглы гугло-экосистемы, то вот можете писать в md, но конвертить во всё тот же Google Slides.

It Is Wednesday, My Dudes, хорошего дня :}

#tool #markdown #ide