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

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

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

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

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

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

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

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

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

ФОРМА

Небольшой размышлений-пост о найме техрайтеров в эру 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.

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

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

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

И личная мини-гордость за Дмитрия Дубилета, (нЕкогда IT директор ПриватБанка и один из основателей самого юзер-френдли банка на этом полушарии - Monobank), министра кабинета министров Украины.

Дмитрий в душе айтишник и мощнейше топит за цифровизацию всего и вся (и особенно документации) и вот сегодня он объявил о пилотном запуске программы по интеграции Google сервисов в гос.сектор. Google Docs, Spreadsheets и Forms по его мнению значительно сократят время на принятие решений и соответственно избавят от необходимости печатать бумажки и возить по ним карандашами.

An ultimate list of resources for technical documentation.

https://tools.doctoolhub.com/

Если можете\умеете в английский на слух, тут вот неплохой подкаст на послушать по дороге домой вечерком. Ана Нельсон, техпис и создатель Dexy говорит об автоматазации тестирования док (кода в доках) и о всяком таком. Лишним не будет:

Ana Nelson: Writing Maintainable Code Documentation with Automated Tools and Transclusion

https://www.maintainable.fm/episodes/ana-nelson-writing-maintainable-code-documentation-with-automated-tools-and-transclusion

Небольшой разбор текущего положения дел в JAMstack-мире:

https://css-tricks.com/jamstack-cmss-have-finally-grown-up/

Spoiler: всё хорошо, все c каждым годом всё больше любят всевозможные статик сайт генераторы.

Что-то давно небыло крутых примеров с docs as comics, сегодня про Docker.

Всем хорошего четверга, погнал я домой

Иногда я всё-таки применяю в работе то, про что пишу. Теперь с удвоенной силой вам советую попробовать в работе линтер прозы Vale, и настроить его в качестве CI на проекте.

Daily reminder о существовании такой великой вещи как Pandoc. Если вам нужно перегнать документ с буквами из одного формата в другой - лучшей вещи нет. Сегодня вспомним как переехать с .md на AsciiDoc

https://matthewsetter.com/convert-markdown-to-asciidoc-withpandoc/

В вечер пятницы немножечко про организацию рабочего пространства, а в частности тулз для писательства. Лично я -- фанат VS Code и всем его усиленно советую, т.к это ультимативный редактор с тонной плагинов и вообще, как грица one stop shop, к тому же, это один из немногих проектов на Electron, который не умервщляет ваш ноутбук (кто-то еще работает за стационарными пк?). НО! Но держать еще один инстанс Хрома не нравится примерно никому и какой-никакой, а удар по батарее и общей производительности железки всё же ощутим, но это решаемо, и решаемо довольно легко.

Нам понадобится:

1. Обыкновенный браузер (фаерфокс или хром, ведь других еще не придумали)
2. MacOS или Linux, или Windows с включенным WSL 1\2.
3. Ровно один бинарник взятый отсюда https://github.com/cdr/code-server
4. 10-20 минут жизни, в зависимости от скорости чтения

Чё в итоге?

Получаем полностью рабочий VS Code, запущенный во вкладке браузера.

Минусы:

- Каждое дополнение нужно скачать вручную из VS Code Marketplace, там есть кнопка Download, скачивается .vsix файлик, его и кормите в уже запущенную веб-версию вскода.
- Дополнение GitHub Pull Requests просит более новую версию вскода, починится с апдейтом сервера, ждём.

Плюсы:

- Ваш ноут скажет вам спасибо
- Кому не покажи вскод во вкладке - все балдеют

Небольшая подборка гайдов o том, как создавать доступный (в плане Accessible) контент:


Google: https://developers.google.com/style/accessibility

Microsoft: https://docs.microsoft.com/en-us/style-guide/accessibility/accessibility-guidelines-requirements

IBM: https://www.ibm.com/developerworks/library/styleguidelines/index.html

Wikipedia: https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Accessibility

У Web AIM есть хорошие статьи для изучения аксессебилити в вебе в целом: https://webaim.org/

Оч познавательная и, что немаловажно, приземлённая статья от кoманды QGIS про то, почему такой большой и полезный (опенсорс!) проект не может в документацию. 

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

Рекомендуется к прочтению и ознакомлению:

https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

P.S: Наверняка вы не прокликаете по всем ссылкам в статье, поэтому я сделал это за вас, вот самая интересная: https://thegooddocsproject.dev/

Пятничный пост в четверг.

На моей памяти это один из величайших образчиков документации, конечно же после док от ИКЕИ. Примерно такого и ждут пользователи, пишите доступно, товарищи

Интересный кусочек истории, IBM Jargon and General Computing Dictionary, такой себе (очень неформальный) гигантский Глоссарий от IBM, и кайфовый образец технической документации.

Написано всё очень лёгким языком, приятно поскроллить и почитать всякое, есть много забавных моментов, можно использовать как источник для своего внутреннего глоссария.

Желаю всем уметь писать так просто и понятно.

https://comlay.net/ibmjarg.pdf