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

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

Других новостей про документацию у меня для вас сегодня нет.

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

Что умеет?

Картинки:

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

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

Ссылки

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

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

Скрипты:

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

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

Favicon-ки:

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

OpenGraph

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

HTML

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Да, это просто инструкция к сетевому фильтру, но КАКАЯ это инструкция! Очень хочется пожать руку автору этого микро-шедевра. Примерно к такой документации мы и должны стремиться, не важно, описание ли это какой-либо библиотеки или инструкция к кофемашине, stay human, братцы (но в меру!)

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

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

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

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

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

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

Руководство по Читабельности от Content Design London — это:

- Ответы на 17 приоритетных вопросов по читабельности;
- Более 80 рекомендаций по читабельности: топовейший  Readability Checklist;
- Всякое полезное по юзабилити-тестированию.

Из всего этого советую обратить внимание и взять на вооружение хотя бы некоторые пункты из чеклиста, дуже гарно!

Пятничный "СМЕКАЛОЧКИ" пост. Всем хороших выходных

Joseph Kato, тот самый мощный тип, что педалит Vale — один из самых важных для меня персонажей современного техрайт-рилейтед тулостроения. Так о чем это я, он запустил Static School, такую себе вариацию небезызвестного StaticGen, но слегка про другое. Сайт все еще в активной разработке, но уже сейчас там есть feature matrix и метрики по скорости сборки (пикрелейтед)