Пока пишется пост с "околоподведениями итогов", вброшу хороший, подробный разбор типов юзер док, бест практисов и тулз (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

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

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

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

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

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

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

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

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

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

#aceccibility #resource #article #en #styleguide

В последние пару недель приходится усиленно макать свои лапки в UX|UI писательство, а точнее — в онбординг в не самом простом приложении. Продавать буквами куда сложнее, чем объяснять что-то ими, поэтому всегда держите в уме вот эту простую весч:

https://www.useronboard.com/features-vs-benefits/

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

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

Конечно же я не имею в виду, что не нужно рисовать красивые иллюстрации и прописывать грамотно всякие feature-flow, просто делать это нужно держа в уме всё вышесказанное и строить онбординг-экспириенс отталкиваясь именно от этих простых, казалось бы, истин

#uiux #en #article #visual