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

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

#visual #example

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

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

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

#testthedocs #en #tool

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

#tool #SSG

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

#tool #en #language

Kinda relevant.

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

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

#career #en

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

#vintage #ru

Vale + GitHub = ❤️

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

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

#testthedocs #en #tool

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

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

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

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

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

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

#markdown #en

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

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

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

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

#tool #en

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

Yet Another UX Tips, но теперь на русском

https://vc.ru/design/92106-koroche-govorya-devyat-pravil-dlya-normalnyh-ux-tekstov

#uiux #ru #article #resource

Обнаружил тут у Hugo (тубо быстрый (like 400 страниц за секунды) статик сайт генератор на Go) на офсайте есть раздел с Showcases, в которых именитые и не очень пользователи рассказывают как они к пришли к Hugo, какие технологии пользуют и какие профиты извлекли. Если вы находитесь в поиске места, куда засунуть вашу документацию, можно полистать и слизать у кого-то весь стэк и подход, это не зазорно!

#SSG #markdown #tool #en

Привет, техписочная!

Связались тут со мной ребята, которые разрабатывают редактор для работы со сложным контентом: техническим, научным, образовательным и т.п. По ссылке ниже будет форма с вопросами по вашему повседневному техрайтерскому воркфлоу, не поленитесь, плиз, поотвечать на вопросы, ведь есть шанс, что ребята запилят что-то действительно полезное, и есть возможность косвенно повлиять на результат и сделать приятно всем.

Если вы совсем не любите заполнять формочки, то там есть вариант просто оставить свои контактные данные и свами свяжутся, и пообщаются в формате интервью.

ФОРМА

Небольшой размышлений-пост о найме техрайтеров в эру DevOps:

https://opensource.com/article/19/11/hiring-technical-writers-devops

Открывал его с мыслью "о, ща про докопс почитаем-с", но псто оказался местами сомнительный, там встречается вот такие предложение:

>A movement called DocOps, out of CA (now part of Broadcom), brought together technical documentation and DevOps practices, but the original team behind the concept appears to have moved on. The effort fizzled out, but I still recommend researching it online.

И вообще докопсу уделён один абзац 🤷‍♂️

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

Энивей, продуктивного денька, техписочная

#career #en #docops