Technical Writing 101 🇺🇦

2021-12-07 15:43:55 В лучший линтер для прозы Vale по просьбам трудящихся завезли улучшенные метрики читабельности.

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

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

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

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

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

Скачать: Vale-compatible implementations of many popular "readability" metrics Открыть/Комментировать

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

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

2021-11-23 13:50:38 # 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 Открыть/Комментировать

2021-11-17 17:05:11 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 Открыть/Комментировать

2021-11-08 11:18:36 Выходим из недельного застоя:

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

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

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

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

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

2021-10-25 12:38:24 О том как быть более лучшим и добрым редактором.

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

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

Читать: The Positivity Pass and Why We Do It: Empathetic and constructive editing produces consistently better results and relationships over time. Открыть/Комментировать

2021-10-14 14:31:14 Write the Docs проводит третий ежегодный зарплатный опрос.

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

Вот, что говорят о целях и пользе авторы опроса:

«We hope this data helps our community members determine what appropriate salary ranges are, and provide a benchmark for future employment-related decisions and negotiations.

Additionally, we’re hoping the results spark discussion of employment-related trends and issues in our industry, including but not limited to the effects of the COVID-19 pandemic.»

Заполнить Documentation Salary Survey 2021 Открыть/Комментировать

2021-10-08 18:46:52 Похоже у нас с вами вот-вот появится своя IDE (IWE?) от JetBrains! Открыть/Комментировать

2021-10-05 14:58:24 GitHub’овский Маркдаун научился в сноски Открыть/Комментировать

2021-09-29 17:44:07 Ситуация: вас наняли техническим писателем в недавно основанную или недавно очнувшуюся и требующую доки компанию. В ней нет ни-че-го (из документации), а должно быть очень многое. За что браться, куда бежать и как определить, что должно быть в Minimum Viable Documentation?

Очень информативный лонгрид под слоганом «Get from nothing to something with MVD» поможет не запаниковать и ответить на все вопросы выше.

Читать: From Nothing to Something with Minimum Viable Documentation Открыть/Комментировать