Technical Writing 101 🇺🇦

И такая вот документация тоже имеет место быть.

Spotify в очередной раз надевает маску доброго opensource-самаритянина и на этот раз делится своими наработками в области документирования. Вся внутренняя документация у них живет на MkDoks и они захотели чтобы всё жило в монорепе. Для создания монореп они написали (и опенсорснули) собственный плагин который умеет в !include (..)/mkdocs.yml.

Больше деталей в официальном блогпосте-анонсе.

#tool #en

Тот Самый Том Джонсон заделал тестов для Технических Писателей. Сложно, на время, но круто. Открыл коменты, делитесь результатами

https://idratherbewriting.com/blog/technical-writing-tests-for-screening-candidates/

В лучшей версии Markdown - Markdeep добавили поддержку pixel perfect картинок. Пользуйтесь, растространяйте, офигенная штука

#markdown #en

Некрасивость документов

У многих профессий ужасно некрасивые документы. Бухгалтерские бумаги, ментовские отчеты, архитектурные планы - все это полный пиздец с точки зрения дизайна, красоты, аккуратности и читаемости. Ебланские таблицы, хуевый контраст, блевотные шрифты - и никто не парится.

Так вот, если не ставить себе задачей полностью посвятить жизнь улучшению какой-либо одной индустрии, не нужно мешать людям.

Если договор из юридического отдела отдать дизайнерам для наведения порядка, то получится в результате очень красивый документ, над которым все остальные юристы будут смеяться как над пидорским говном. Если на архитектурном плане заменить "узкий архитектурный шрифт" на что-то читаемое и нормальное, то это как если сообщить всему архитектурному сообществу, что этот план составлен непрофессионалами.

Все кривожопые и уродские стандарты в разных профессиях на самом деле очень важны. И просто так улучшать их нельзя, нужно сто раз сначала подумать. Это примерно как фуражки у военных - они максимально дебильные, но зато они одинаково дебильные у всех. В этом и заключается секрет - подчинение стандарту, даже мудацкому, позволяет профессиональному сообществу очень точно определять наиболее опытных коллег.

Vale + GitHub = ❤️

Свежий GitHub Action который делает вы уже поняли что

https://github.com/marketplace/actions/vale-linter

#testthedocs #en #tool

Очень нравятся военные инструкции, они очень лаконичные, в них нет ничего лишнего, они выверены от и до, и их единственная цель — спасать жизни. На фото выше инструкция к Сигнальному Зеркалу (такой себе переносной Гелиограф), напечатанная на задней его стенке. С помощью такого зеркала потерявшийся в морском бою или выброшенный на необитаемый остров солдат мог подать сигнал пролетающему самолёту или проплывающему кораблю. Дальность сигнала-зайчика с зеркала такого размера достигает +-20км.

#vintage #ru

Kinda relevant.

История о том как соло техрайтеру предложили стать Technical Content Manager'ом, нанять себе напарника и менторить его.

https://medium.com/gsoft-tech/hiring-a-human-73c6ed5e0e66

#career #en

💥🎂

Ловите словарик терминологии на 1314 слов в plaintext формате. Сам словарь выкорчевали из Cybersecurity Style Guide, но подходит для всего около-IT'шного.

#tool #en #language

Для беженцев с MadCap Flare на Sphinx нашелся полезный скриптец миграции, который поможет сбросить оковы проприетарщины и прильнуть к лону опенсорца.

#tool #SSG

Начнем неделю с приятной новости, Vale Server обновился до версии 1.3.

Из приятных улучшений:

- Интеграция LanguageTool (а это 2500 правил для Английского);
- Поддержка быстрого (два клика) исправления ошибки в тексте в VSCode, Atom и Sublime.

#testthedocs #en #tool

Больше иллюстрированных гайдов богу иллюстрированных гайдов, сегодня про OAuth и OpenID Connect:

https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc

#visual #example

Нажимать надо на раздел "Payments". Пользуюсь приложением (это такси Bolt, бывшие Taxify) уже довольно давно и это настолько нелогичное решение, что я ещё ни разу не нажал куда надо, всегда иду сразу в "Promotions". 🤦‍♂

#example #ru

#example #ru

Fantastique.

Шикарнейшая подборка инфографико-инструкций, описывающих как работают популярные алгоритмы, не используя ни единого слова, как инструкции IKEA, но про другое.

Более точное описание на самом сайте: "IDEA is a series of nonverbal algorithm assembly instructions, [...]. The instructions explain how various popular algorithms work, entirely without text. This also allows the instructions to be understood interculturally."

https://idea-instructions.com/

#visual #en #example

Друзья, по мотивам регулярных вопросов из зала набросал статью о том, дружат ли agile и управление знаниями https://habr.com/ru/post/472612/ . Очень жду вас в комментариях :)