https://tldrlegal.com/ — отличный по реализации, но удручающий по смыслу сервис. На сайте собраны всемозможные software лицензии (GPL, MIT и т.д) описанные максимально простым языком, который понимают все, а не только юристы. This is how documentation should work

Часто работаешь с интерфейсами? Мож изредка делаешь опросничек-другой в помощь менеджменту? А может ты тесно завязан на продукт? Учись делать правильно и помогай тем, кто пока еще делает не до конца правильно.

Рекомендации по использованию чекбоксов и *chuckles* радиокнопок:

- Checkboxes vs. Radio Buttons

У статьи хороший финал, где объясняют, почему нужны эти гайдлайны и что это не пустой трёп и что "if you don't, you'll be taken for an amateur."

Скриншоты! Как много в этом слове!

Излюбленная тема всех техрайт чатиков — обсуждать в какой тулзе они делают скрины, но это так же скучно, как слушать про чужие сны. Давайте лучше почитаем свежую статью из ISTC Communicator о том, как сделать так, чтобы снятием свежих скринов нужно было заниматься не каждый апдейт продукта. А поможет нам это сделать simplified user interface, относительно свежий подход к созданию таких себе "абстрактных" версий скриншотов интерфейса (см рис.1).

Если вам интересно почитать еще об этом, то там в конце статьи есть раздел Further Reading, а если хочется вдобавок и пообщаться про это, то для этих дел есть отдельный (англоязычный) Слак-чат

​​Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.

Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.

Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.

Книгу можно купить на сайте издательства. Приятного чтения!

🙄

Если в PM или BA перекатываться не хочется, можно попробовать стать Скрам Мастером, somehow related

Все мы любим Docs as a Code, но иногда этого становится мало и хочется ВСЁ as a Code, поэтому в сегодняшней подборке Презентации as a Code (с уклоном в Markdown)

Начну со своих любимых тулз:

Marp — нЕкогда Electron (не переставайте читать на этом месте) приложенька, которая кушает маркдаун и делает из них собсно презентацию, но товарищи разработчики видимо протёрли глаза и наконец поняли что Электрон — есть корень зла и свернули сие богомерзкое деяние в пользу богоподобного расширения для VS Code

Deckset — если в вашем распоряжении есть MacOS и необходимость хоть изредка делать презентации то просто жмите на ссылку и дальше не читайте. Лучшая аппка.

reveal.js — фреймворк для HTML-презентаций. Умеет вложенные солайды, Markdown ☜(ﾟヮﾟ☜), экспорт в PDF, отдельные спикер ноуты. Если впадлу что-то там мудрить, то есть онлайн-редактор. Можно закомбинить это дело с Pandoc.

remark.js — чуть более tricky, чем reveal, но дело делает. Есть подсветка кода в слайдах, нормально всё скейлится, конечно же умеет MD, отдельные спикер ноуты и всякое такое.

hackMD — это как Google Docs, но для Markdown. Тут оно за тем, что там есть режим презентаций :}

Не про Markdown, но Slides as a Code вполне себе — eagle.js — фреймворк для слайдов поверх Vue.js. Самая выпендрёжная из всех систем в списке, без лишних слов:  посмотрите демки, до конца.

Notable mentions:

md2googleslides — если вы всё никак не слезете с иглы гугло-экосистемы, то вот можете писать в md, но конвертить во всё тот же Google Slides.

It Is Wednesday, My Dudes, хорошего дня :}

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

https://blog.usejournal.com/proportional-vs-monospaced-numbers-when-to-use-which-one-in-order-to-avoid-wiggling-labels-e31b1c83e4d0

Просто посмотрите на приведенные примеры-картинки в статье. Меня, лично, очень бэдит с такого, давайте вместе стараться, чтобы вот так небыло.

Technical Writing: Readability and Text Metrics

Из этой книги вы узнаете:

- Почему метрики важны в техническом письме.
- Как измерить эффективность вашей документации.
- Топ 5 текстовых метрик для пользовательской документации.
- Как проверять техническую документацию на ошибки.
- Где взять все необходимые метрики.

Читая местные техрайт чаты и наблюдая повторяющиеся изо дня в день вопросы, всё меньше боюсь постить сюда что-то очевидное (но, конечно, полезное), поэтому ловите 9 действительно хороших, годных советов по UX-райтингу (не обращайте внимание на название статьи, внутри релевантно):

https://medium.com/@johnamwill/9-simple-but-powerful-ux-writing-tips-for-designers-83ec1ca96561

JetBrains давно используют собственный инструмент для документации, а теперь хотят его опубликовать.

Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.

Дастин Морис Горски, мейнтейнер фреймворка Giraffe, делится своими наблюдениями и мыслями по поводу документации опенсорс проект(а)ов:

https://dusted.codes/open-source-documentation

key takeaway из статьи:

I put all initial documentation into the README.md file inside my Git repository.

Almost two years-, nearly 50 releases-, 47 total contributors-, more than 800 GitHub stars and more than 100 merged pull requests later the project's simple documentation approach hasn't changed much, and to be honest I have very little motivation to do something about it.

The main reason why I'm not particularly excited about migrating Giraffe's documentation to a different place is because I actually believe that the current way of how documentation is handled by Giraffe is a perfectly well working solution for its users, its contributors and myself.

In Giraffe the entire documentation - a full reference of what the web framework can or cannot do and how it integrates and operates within the ASP.NET Core pipeline - is placed in a single DOCUMENTATION.md file inside the project's Git repository, right next to the README.md file.README.md file inside my Git repository.

Almost two years-, nearly 50 releases-, 47 total contributors-, more than 800 GitHub stars and more than 100 merged pull requests later the project's simple documentation approach hasn't changed much, and to be honest I have very little motivation to do something about it.

The main reason why I'm not particularly excited about migrating Giraffe's documentation to a different place is because I actually believe that the current way of how documentation is handled by Giraffe is a perfectly well working solution for its users, its contributors and myself.

In Giraffe the entire documentation - a full reference of what the web framework can or cannot do and how it integrates and operates within the ASP.NET Core pipeline - is placed in a single DOCUMENTATION.md file inside the project's Git repository, right next to the README.md file.

Трансляция Write the Docs Prague.

Сегодня и завтра в Праге проходит конференция Write the Docs.

Программа на сегодня, 16 сентября:

— The Super Effective Writing Process of Grammy-winning Artists

— How to write the perfect error message

— How to launch your startup with good docs

— Surprise! You're a designer now

— Documenting known unknowns

— Write the API docs before the API exists

— Disagree with “I Agree”. Enforcing better data privacy through the language of documentation

— Inclusive environments are just better: science says so

Есть бесплатная трансляция: https://www.writethedocs.org/conf/prague/2019/livestream/.

Интересный подход к процессу ревью\апдейта документации внедряет Британский Government Digital Service.
(GDS — Британская контора, которая (как я понял) топит за цифровизацию всевозможных гос. процессов)

GDS написали своего бота\тулзу, который(ая) напоминает проверить актуальность доки. Каждая страница имеет 3 переменные: дату последней проверки, кто должен ее просмотреть, и как скоро страница должна быть снова пересмотрена.

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

Еще только вторник, а отличные новости уже подоспели.

Новый мажорный релиз всеми любимого инструмента тестирования документации Vale! Теперь 2.0!

Из нового:

[brkng] Vale теперь не содержит в себе сторонних проверок. write-good, proselint, Joblint и другие теперь вынесены в отдельный репозиторий;
[new] Можно линтить XML, в т.ч DITA;
[new] Расширенные скоупы проверок, позволяющие более гранулировано писать правила для линтера;
[new] Добавлен опциональный параметр --config, позволяющий вручную указать путь к файлу конфигурации.

Очень и очень круто!

Люблю читать всевозможные документация-рилейтед саксесс-стори. В этот раз про успешный перекат на #AsciiDoc

https://medium.marqeta.com/write-your-developer-docs-in-asciidoc-78febf2a1304