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

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

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

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

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

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

#article #example #en

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

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

#example

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

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

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

https://comlay.net/ibmjarg.pdf

#example #vintage #en

Cтырено с хорошо начавшейся и, судя по всему, затихшей инициативы по созданию "документационного компендиума"

Awesome Technical Writing Sources:

My Tech Writing Process - Amruta Ranade
Developer to Technical Writer - r/technicalwriting
awesome-github-templates - devspace
makeareadme - dguo
What nobody tells you about documentation - Daniele Procida
3 Essential Components of Great Documentation - Eli B
Inspiring techies to become great writers - Cameron Shorter
Technical Documentation Writing Principles - Cameron Shorter
Building Our Documentation Site on platformOS — Part 2: Content Production and Layouts - Diana Lakato
Google Developer Documentation Style Guide - Google
README Maturity Model - LappleApple
Markdown Style Guide - Ciro Santilli

#styeguide #markdown #resource #article #en

Пока пишется пост с "околоподведениями итогов", вброшу хороший, подробный разбор типов юзер док, бест практисов и тулз (hint: тулзы можно не смотреть, там дженериковенько). Очень понравились схемки, надобно и себе куда-то парочку утащить
https://www.altexsoft.com/blog/business/technical-documentation-in-software-development-types-best-practices-and-tools/

#article #en

Если вы имеете дела с доками которые в конечном счёте становятся html, то возможно эта тулза (html-proofer) вам подойдет.

Что умеет?

Картинки:

Проверяет img элементы:

- Все ли ваши изображения имеют alt-тэги
- Не нарушены ли ваши внутренние ссылки на изображения
- Отображаются ли внешние картинки
- Все ли ваши изображения содержат HTTP

Ссылки

Проверяет а, link элементы:

- Работают ли ваши внутренние ссылки
- Работают ли ваши внутренние хеш-ссылки (#linkToMe)
- Работают ли внешние ссылки
- HTTPS-ли ваши ссылки
- Включен ли CORS/SRI

Скрипты:

Проверяет `script` элементы:

- Работают ли ваши внутренние ссылки на скрипты
- Загружаются ли внешние скрипты
- Включен ли CORS / SRI

Favicon-ки:

- Валидны ли фавиконки

OpenGraph

- Валидны ли изображения и URL-адреса в метаданных OpenGraph.

HTML

- Валидна ли ваша HTML-разметка. Это делается с помощью Nokogumbo для проверки правильности разметки HTML5.

P.S пишу с мобильного клиента, сорри за верстку, таков путь

#DocsAsCode #tool #en

Довольно осознанные заметки от человека, регулярные задачи которого не особо-то и включают в себя написание документации. Сел. Разобрался. Написал для себя заметки. Поделился. Вот молодец.

Есть выжимка из уже знакомых вам по этому каналу ресурсов, но, как грица, nevertheless.

https://mkaz.blog/misc/notes-on-technical-writing/

#article #en

У нас уже было как-то про версионирование, вспоминали про semver, забавный semantical versioning и конечно же calver. А тут (в 2018) чуваки сделали под себя гибрид semver + calver, но с кошаками. I present to you Semancat versioning!
https://blog.avatao.com/semancat-versioning/

#versioning #en #article

Так как мы живем в неидеальном мире, вас могут попросить писать документацию по ГОСТ'ам. А что делать если выходить из зоны комфорта всё еще не хочется, а хочется и дальше сидеть в уютном VS Code и строчить в Markdown?

GOSTdown — набор шаблонов и скриптов для автоматической вёрстки документов по ГОСТ 19.xxx (ЕСПД) и ГОСТ 7.32 (отчёт о научно-исследовательской работе) в форматах docx из файлов текстовой разметки Markdown.

#tool #ru

Внезапно MasterCard тоже делится (релевантными для нас) знаниями, ещё и контрибьютит в опенсорс.

В статье представлен небольшой кейс об автоматизации генерации диаграмм из текста (TL;DR: они пользуются моим любимым Mermaid).

Автор рассказывает зачем вообще нужны диаграммы в доках, кто их читает и почему выбрали именно mermaid

https://developer.mastercard.com/blog/automating-diagram-generation-from-text

#diagram #en #article #tool

Про иноды и хардлинки в 6 панелях комикса. Просто и доступно

#example #visual #en

Мы всей редакцией очень любим документацию в виде комиксов (да и просто комиксы без документации тоже). Подписчица Ксения (спасибо) скинула в личку ссылку на полную подборку комиксной документации этого автора. У мадам очень занимательный и хуман-френдли блог с кучей дельных советов, как, например, "как задавать правильные вопросы" (этого скилла нет у бОльшего числа людей, чем хочется думать)

#example #visual #en

​Как тестирование бумажной инструкции привело к изменению части устройства

Отличная статья про тестирование продукта вместе с документацией.

Краткий пересказ
Делали сложную железку (подсветку для телевизора), которую пользователь должен был самостоятельно монтировать. Установить должна смочь любая домохозяйка. Решили протестировать на людях железку и две разные инструкции. В итоге переделали все.

Самый сок
* Проблема не всегда в документации, иногда нужно менять сам дизайн и техническое решение.
* Пример инструкции для чего-то нестандартного (я такое коллекционирую).
* Можно посмотреть процесс изменения инструкции.
* То, что люди на тестах не читали инструкцию до конца, еще не означает, что ее не нужно делать.

Послесловие
Меня осенило, что символ ✂️(ножницы с пунктиром) одна из первых символьных инструкций, как и 💾 (дискета). Так?

#экспериментыналюдях #намвсемнужнапомощь