О том как быть более лучшим и добрым редактором.

Open Strategy Partners рассказывают и показывают на своем примере что такое Позитивный Подход при вычитке чужих работ.

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

🔗 Читать: The Positivity Pass and Why We Do It: Empathetic and constructive editing produces consistently better results and relationships over time.

Выходим из недельного застоя:

1. Статья о шести характеристиках хорошей докментации. Тут без откровений. Характеристик хорошей документации куда больше, но помнить об основе — надо

🔗Читать: Six characteristics of good docs

2. Если вы любитель «second brain» приложений а-ля Notion, есть большая вероятность, что вы уже открыли для себя Obsidian, про который я когда-то уже пару раз писал. Из подписчиков точно кто-то пользовался в компании. Так вот, для него вышел плашин с лучшим линтером простого, челвоеческого английского — Vale. Есть поддержка как и платной серверной версии, так и бесплатной CLI.

🔗 Читать: New plugin: Obsidian Vale

3. Из личного опыта. Писал тут когда-то про Mark — утилиту для синхронизации .md файлов с Clonfluence, которую можно запрячь в CI и вот это вот всё. Пост вызвал относительно бурную дискуссию и в том числе упрёки, что ничего там не работает. Добрался я таки до этой тулзы сам и имею сказать, что все работает. Пользоваться рекомендую Докер-образом и в качестве пароля передавать API-токен. Работает даже на Маке.

JetBrains запостили у себя статью, которая у меня была отложена на поделиться с вами попозже, так что here we go!

В статье автор усиленно сетует на стагнацию техрайт тулинга, на отсутствие каких-либо стандартов (да, десятки сортов markdown, asciidoc, DITA и прочие, это мы про вас), отсутствие версионности, предназначенной для документации и всякое такое (статья хорошая, советую прочесть, проникнитесь может)

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

🤔 К чему пришли в JetBrains в своей новой IDE для Техписов:

>What we’ve come up with for ourselves is a semantic XML-based markup with smart completion along with Markdown support. And you can mix the two in any proportion to stay light and still inject more complex markup if you need extra features like tabs or advanced code blocks.

🔗 Читать: Better docs, less pain: the case for new docs-as-code standards

# Code needs documentation to become a project# Code needs documentation to become a project

🐙 GitHub выкатила красивейший data-driven (простите) отчет о своей деятельности за 2021 год: The 2021 State of the Octoverse. Там вам и графики, и статистика пользователей, и самые популярные языки.

Отчет разделен на 4 части, Overview, что-то для программистов, про поддержку коммьюнити и 🥁документация!🥁! Нас особенно интересует конечно же последнее.

Раздел про документацию полон интересной статистической информации и выводов из нее. Особенно понравился раздел о том, что "GitHub Issues are documentation too" и сразу же за ним совет создать Good First Issues guide.

Однозначно материал месяца, обязательно к ознакомлению

🔗 Читать: Creating documentation to support developers

❓ Не совсем по теме документации, но обнаружена офигенная аппка на мак — Fig (https://fig.io/) добавляет VSCode-лайк автокомплит всем командам в терминале.

Соответственно вопрос, стоит ли делиться годными штуками, которые не сильно и связаны с докумментацией, но косвенно помогут в ее создании?

📓 В лучший линтер для прозы Vale по просьбам трудящихся завезли улучшенные метрики читабельности.

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

- длина слов и предложений,
- сложность синтаксических конструкций (наличие однородных членов предложения и предложно-падежных групп, перегруженность причастными и деепричастными оборотами),
- показатели частотности слова,
- уровень абстрактности лексики,
- обилие терминов

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

Среди новых метрик:

- Automated readability index (ARI)
- Coleman–Liau
- Flesch–Kincaid
- Flesch reading ease
- Gunning fog
- LIX
- SMOG

🔗 Скачать: Vale-compatible implementations of many popular "readability" metrics