Переведенный курс Тома Джонсона по документированию API обзавёлся сайтом:

https://starkovden.github.io/

Доступны записи API THE DOCS, AMSTERDAM:

- Lorna Jane Mitchell: GitHub as a Landing Page
- Aaron Verber: Leaping Forward: Finding the Future of Your API Docs
- Sven Strack: Engineer Stunning (API) Documentation
- Jaap Brasser: Advancing Your API Strategy in an Infrastucture World
- Anthony Roux: What Makes an API Product Successful
- Maria Garcia: Bulletproofing Your APIs: Why Users' Feedback Matters
- Mark Simpson, Alexandra Stramarko: Business Integration Made Easy with APIs
- Kelsey Lambert, Sejal Parikh: An Inside Look at a Large-scale Writer-driven REST API Doc Solution at Salesforce
- Alvaro Navarro: Effective API Governance: Lessons Learnt
- Phil Sturgeon: API Descriptions as Production Code
- Steph Shin: How to Embed UX Thinking in your Next API

https://pronovix.com/event/api-docs-amsterdam-2019

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

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/

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

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

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

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

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

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

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

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

💥🎂

Kinda relevant.

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

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

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

Vale + GitHub = ❤️

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

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

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

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

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

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

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

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

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

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