Сегодня в Google Docs прилетела проверка Spelling and grammar, выглядит вот так. Круто, чё!

Сегодня небольшая подборочка проектов за которыми наблюдаю сам ну и вам советую, вдруг:

1. https://github.com/errata-ai/vale - один из самых мощных линтеров простого человеческого английского. Поддерживает крайне хитрые правила линтовки, если сильно заморочиться - может выйти свой стайлгайд, который через интеграцию в CI можно легко и без особых болей внедрить в команду\контору.

2. https://github.com/errata-ai/vale-server - CI это конечно хорошо, но блин, это сложно, интегрировать вот это куда-то, Тревисы и иже с ним. Не то! Так вот, запустился новый проектик по интегрированию Vale в сендбоксед приложения (aka Google Chrome (а значит и в ваш любимый Google Docs), Word и т.д). Hyped!

3. https://github.com/codercom/code-server - coder.com опенсорснули своё решение и теперь предоставляют Докер контейнер который запускается в пару кликов и позволяет запустить VSCode прямо во вкладочке браузера. Очень хочется себе такое, но пока не понял зачем.

Ухты-ухты-ухты, тут вот New Your Times заопенсорсили своё документационное решение.
Деплоится на Хероку в один клик и живёт поверх ваших документов в Google Docs!

https://github.com/nytimes/library

Google Docs в кой-то веки научился нативным якорным ссылочкам. Теперь никаких костылей в виде "закладок".

Маленький, но полезненький сайтец со всякими месседжами на все случаи жизни. Всё написано людским языком, ну как те самые лоадинг скрины в Slack, всё как вы любите. http://speakhuman.today

Что-то в последнее время то ли меньше времени на поиск и чтение всяких полезностей стало, то ли потеплело и пипл разленился писать.
Если вдруг у вас есть чем поделиться, чего еще небыло тут - милости прошу, кидайте всякое на @SuckMyNuts

Сегодня микростатейка про "дружбу, не вражду" UX и Тех. Документации

https://medium.com/gsoft-tech/docs-and-ux-its-a-collaboration-not-a-competition-b5076390c87a

А еще в новомодных GitHub'овских Actions появилась линтовка с помощью Vale, зацените, но оно оч сырое:

https://github.com/marketplace/actions/vale-lint

Сегодня в эфире две полезные приложеньки

1) https://writefullapp.com - приложение/расширение для браузера (наверняка вы о нем уже слышали, but still), позволяет быстренько проверить словосочетание на популярность, сравнить две фразы друг с другом и всякое такое. Очень наглядно и частополезно, советую.

2) https://github.com/wkhtmltopdf/wkhtmltopdf - тулза которая "headless'ly" конвертит HTML в PDF (или картинку). Никаких зависимостей, чистый бинарничек, CLI, красота!

Такой вам Daily Reminder о том, как определить Passive Voice

https://twitter.com/johnsonr/status/259012668298506240

Обнаружил и незамедлительно намазал свой VSCode оч красивым шрифтом с ублажающими очи лигатурами. Вы только полюбуйтесь! https://github.com/tonsky/FiraCode

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

https://medium.com/@jgee/what-i-learned-in-two-years-of-moving-government-forms-online-1edc4c2aa089

Немного о пользовательской документации

Копаться в документации к софту — зачастую катастрофа. На Хабре рассказали про главные проблемы пользовательской документации и как их исправить.

Проблема 1. Непонятные, плохо написанные статьи.
1. В большинстве ситуаций, кроме описания редких фич, предполагайте, что пишете для новичка.
2. Определите полезное действие статьи и решите, что должен сделать читатель после её прочтения.
3. Избегайте неточностей, канцеляризмов, опечаток и лишней информации.

Проблема 2. Статьи не отвечают на все вопросы.
1. Планируйте документацию по новым функциям когда их только начинают разарбатывать, а не когда уже тестируют.
2. Документация должна отвечать на запросы пользователей — посмотрите, что ваши клиенты спрашивают у поддержки или поисковиков, и ответьте на эти вопросы.
3. Документация не пишется раз и навсегда, она должна постоянно совершенствоваться на основе обратной связи.

Круто-прикруто.

Mozilla релизнула свою систему (спецификацию, имплементацию и набор best practices) для "естественно звучащих" переводов. Потыкать можно на оф сайте, а почитать как там всё устроено и собсно зачем и почему это нужно - можно в официальном блоге Мозиллы или на wiki в GitHub.

Рекомендовано к ознакомлению, благое дело, подошли с умом.

О пользе чеклистов:

>Смертность после операций в Шотландии снизилась на 37% с 2008 года, что объясняется внедрением чеклиста безопасности.

https://www.bbc.com/news/uk-scotland-47953541

Документация? Документация!

Не болейте.

https://chrome.google.com/webstore/detail/noncontiguous-text-select/ajbomhojbckleofgngogoecoaefclnol

Очень неплохо бы что-то нативное такое заиметь, пусть уже Apple "изобретёт" это у себя в очередной MacOS, чтобы другие к себе унесли через полгода. Такое надо.

Приятно знать, что не у одного меня горит от хреновых чейнджлогов больших приложений. Я понимаю, что там А/Б тесты, сервер-сайд фичи и что далеко не всем это нужно, и никто вообще их не читает, но это вообще не дело.
https://www.techwrap.net/tech/play-store-app-changelog-need-consistency/

В последнее время всё чаще и чаще вижу как многие перекатываются то на Gatsby, то на Hugo (причем не только для документации, но и для личных бложиков)

Вот отличная саксесс стори о переходе с богомерзкого Вордпресса на богоугодный Hugo

https://www.presslabs.com/how-to/documentation-hugo/

Приятный и понятный гайд по ведению документации в Confluence.

Гайд покрывает такие темы как:
- Почему Confluence
- Создание топиков
- Коллаборация
- Переиспользование контента
- Версионирование
- Публикация
- Локализация
- Conditional контент

Кроме того, там лежит приятный док. процесс для Agile команд

Пользуйте!

https://www.k15t.com/rock-the-docs

На Season of Docs уже доступен список опенсорс проектов в которые можно контрибьютить документацию:

https://developers.google.com/season-of-docs/docs/participants/

Второй день не пойму related ли эта тема тут или нет, но я люблю буковки поэтому ловите.

Детальный и супер задротский разбор пресловутой PDF-ки Mueller Report. Там обсуждают PDF стандарты и их нарушение, выясняют как была создана эта пдф-ка и что пошло не так, а также софт которым цензурят такие документы и всякое такое. Всё это дело рассказывает дядька, который >ISO Project co-Leader for ISO 32000 (the PDF specification) and Project Leader for ISO 14289 (PDF/UA)

https://www.pdfa.org/a-technical-and-cultural-assessment-of-the-mueller-report-pdf/

Немножко про организацию документации.

https://medium.com/@brooke.wayne/how-to-organize-your-docs-bd797c616b48

Статья описывает базовые вещи, но интересный тейкэвэй оттуда это термин Undernets:

>Undernets are the “non-formal and unintentionally walled off bits of knowledge that [folx] document in private”, also known as “rogue docs or sheets [others] create for themselves. These are often incorrect, out of date, or not shared with the entire team.”