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

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

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

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

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

В лучшей версии 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

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

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

An ultimate list of resources for technical documentation.

https://tools.doctoolhub.com/

#resource #article #SSG #tool #en

Если можете\умеете в английский на слух, тут вот неплохой подкаст на послушать по дороге домой вечерком. Ана Нельсон, техпис и создатель 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

#video #testthedocs #en #article

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

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

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

#SSG #article #en

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

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

#visual #example #en

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

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

#markdown #asciidoc #tool #article #en

В вечер пятницы немножечко про организацию рабочего пространства, а в частности тулз для писательства. Лично я -- фанат 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 просит более новую версию вскода, починится с апдейтом сервера, ждём.

Плюсы:

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

#vscode #ide #ru

Небольшая подборка гайдов 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/

#accessibility #article #styleguide #en