И мы снова в эфире.

Извиняемся за задержку в публикациях, вся редакция увлеченно играла в Last Of Us II 👉 👈 🙄

Пост номер один -  для любителей DITA, XML и прочих аббревиатур из прошлого. Но допустим, что вы таки попали в экосистему DITA (я точно знаю, что у меня есть читатели-фанаты DITA), но не хотите выглядеть как старик, а хотите если не AsciiDoc/rST, то хотя бы Markdown, и чтоб с валидацией, линтингом и вот это вот всё.

Предлагаю вашему вниманию вебинар на тему "Oxygen Markdown Support", в котором рассказывают как сделать всё вышеперечисленное прямо в Oxygen XML Editor

Второй пост - комбинированный:

Избавляемся от нарочитых и подсознательных предвзятостей, опять же с помощью наших верных друзей - линтеров и засовываем Grammarly в VS Code

- Linter (вот так просто) на Руби (eww) помогает с inclusive language: gender-coded words, use of pronouns and misused words.
- Я когда-то давно писал о нём, но раз такое дело, то есть еще и linter-alex (alexjs)(в честь гендерно-нейтрального имени Саша), который делает почти почти то же самое.
- Кто-то захакал Grammarly прямо в VS Code, расширение конечно же сразу снесли с стора с экстеншнами, но еще можно скачать vsix файл, установить его в ручную и поклацать

Я некогда писал об Obsidian. Это такая "база знаний", но без "облачных" примочек, живёт это дело поверх локальной папочки с .md файликами. Можно смотреть связи и всякое такое.

Недавно на глаза попалось нечто похожее под названием Foam. На этот раз всё обёрнуто в vscode и приправлено довольно популярными расширениями. Автор предупреждает, что пока всё готово примерно на ~10%. Можно залайкать и следить за релизами, авось чего и вырастет из этого

Познавательная "behind-the-scenes "-статейка от GitHub о том как они перезапускали docs.github.com и с какими проблемами сталкивались и как их решали.

https://github.blog/2020-07-02-how-we-launched-docs-github-com/

В далёком 2016 Airbnb поделились своей болью со скейлингом шаринга (простите) знаний и вариантами того, как это дело обуздать. В статье без откровений, но мне она нравится, подойдет как старт для тех, кто только задумался о построении системы по обмену знаниями внутри компании/команды.

И все эти годы они спокойно себе пилили свой 🚲. Судя по чейнджлогам - выглядит интересно. Делюсь, может кому подойдет.

Документация по этой системе живет тут

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

У меня сейчас проходит небольшой цикл ревью очень маленьких кусочков текста (те самые microcopy) которые я писал довольно давно. И имею сказать, что усилия, требуемые, чтобы получилось ХОРОШО несоизмеримо выше усилий, которые нужно приложить, чтобы писать обычную (конечно же читабельную) документацию.

Очень согласен с этим твитом, can relate, так сказать:

https://twitter.com/krnswry/status/1283075386495074307

Дано: посудомойка с 5 режимами.

Необходимо: понять что делает второй пункт.

Вывод: опозориться можно и в документации, состоящей из одного слова и одной картинки. Иногда (при неумении/неопытности - всегда) лучше не креативить, а писать как есть. Только узнав и научившись как делать нужно, можно начать делать так, как хочется и гнуть (ну ладно, more like подгибать) правила под себя.

Hint: чтобы посмотреть правильный ответ, нажмите на 💡

Я очень люблю узнавать о чужих процессах и читать о том как их строят и вообще о внутренней кухне. Недавно подвернулся сайтец Greater Greater Washington, на котором чуваки на волонтёрской основе топят за все хорошее и против всего плохого в своем округе, улучшают район и всячески его развивают.

Кроме оффлайн активностей, товарищи ведут активный блог и ведут его основательно, у них даже есть свой стайлгайд, и они даже его опубликовали. Да, он не технический, но полезно и интересно посмотреть на чужую работу.

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

Это пример отличной коммуникации и knowledge sharing attitude, будьте как Greater Greater Washington!

ReadMe (которые personalized, interactive developer hubs) ведут офигенский documentation-related блог, рекомендую!

Сегодня попалась на глаза их обширная статья о том как начать вкатываться в Swagger + OpenAPI  документацию. Темплейты, бест поактисы, тулзы и примеры. Всё к вашим услугам! Нормально подойдет для базовых познаний что там да как.

Бонус трек - Mockoon, мокалка API, которая умеет всё локально (No remote deployment, no account required, open source.), еще и кроссплатформенная.

К вопросу о том как выпрыгнуть из цикла Нужна работа --> Для работы нужен опыт --> Для опыта нужна работа. Получить хоть какое-то портфолио для начала карьеры в техписательстве или просто помочь сообществу если есть пара свободных часов в день вполне реально.

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

Пост оч грамотно структурирован, а что главное - есть ссылка на "How to Contribute to Open Source for first-timers and for veterans."

Очень (очень!) хорошая статья от Nuclino о том, почему никто не читает документацию, почему это нормально и варианты разрешения этой ситуации. Nuclino сами занимаются разботкой софта для Обмена Знаниями, такой себе аналог Notion, поэтому они знают о чем говорят.

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

Ключевые моментики из статьи:

- Никто не читает документацию и это ОК
- Документация нужна не чтобы её читать, а чтобы с ней консультироваться
- Не пишите документацию, только ради написания. Никому не нужен огромный, толстый, пускай и  всеобъемлющий кусок текста
- Пишите документацию держа в голове то, что скорее всего, её будут искать в поиске, а не просматривать все оглавления
- Пишите небольшие кусочки документации и пользуйтесь кросс-ссылками, ссылаясь на другие, такие же небольшие кусочки док.

Бонусный трек: их же статья про ценность документации и сколько может стоить отказ от обмена знаниями.

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

- Microsoft Writing Style Guide
- Google Developer Documentation Style Guide
- Apple Style Guide
- DigitalOcean Product Documentation Style Guide
- GitHub Style Guide
- GitLab Docs Documentation Style Guide
- Mailchimp Content Style Guide
- RedHat Style Guide
- Rackspace Style Guide for Technical Content
- Splunk Style Guide

Другие полезные стайлгайды:

- Federal plain language guidelines (USA)
- IEEE Editorial Style Manual for Authors
- IBM developerWorks editorial style guide
- Online Writing Lab (OWL) at Purdue University
- Paramedic Method: A Lesson in Writing Concisely
- University of Oxford Style Guide
- The Diversity Style Guide
- Progressive’s Style Guide

Тут наше любимое! Статейка чтоб была под рукой в следующий спор

Функционал или функциональность 

Пишете про технологии, стартапы и приложения — статья точно поможет поставить жирную точку в этом споре:
 
https://nepishi.ru/s/function/

Залежалась в закладках статья (статья старая, кидал вам её сюда еще в 2018, а перевод свежий 🇷🇺) про UX Writing от Гугла.

Статья особенно полезна примерами как делать и как не.

Там и про бренд войс и про тон и, собственно, очень полезный чеклист, чтобы ничего не упустить! Если не осилили её на английском, крайне советую прочитать сейчас

Интересный подход к документированию кода. Вместо комментариев и "традиционной" документации, сервис предлагает "истории" (нет, не сторис как в инстаграме, а больше user story).

Выглядит всё это дело как интерфейс отладчика, в котором можно расставлять брейкпойнты (есть даже визуальный call stack). Такой сторей удобно онбордить новых товарищей в проект или красиво пояснить свой пуллреквест. Ну и да, конечно же там есть поддержка гифок, мемчиков и всякого такого.

Посмотреть готовые сторис или создать свою можно тут --> StoryTime.dev

Пишите понятную документацию, рисуйте её значками и символами если нужно, упрощайте, и делайте всё для людей, но будто для детей, чтобы небыло вот так:

https://twitter.com/jaredpalmer/status/1293537083399839744?s=20

Всем хорошей пятницы и приятных выходных