Я почти никогда не читаю чужие личные итоги года, зато люблю ретроспективы того, что было сделано в рамках какого-то проекта или блога.

Моё ретро за год:

1. Написал статью про сравнение SSG, которая действительно понравилась людям. Она про мой субъективный опыт, но, судя по реакции, людям не хватало такого базового сравнения. Свой опыт вкатывания в айти я кстати тоже описал, аж в трёх частях.

2. Написал намного больше постов про всякое интересное — от переводчика для синдарина и погружения в виды арабских цифр до истории термина pull request и жёсткого разбора сильнее всего раздражающей меня фразы про исключения, подтверждающие правила.

Я смог найти темы, которыми действительно хочется делиться, не делая из своего канала чтото исключительно профессиональное — большая радость для меня.

3. Как младший барсук дальнего леса из администраторов в крупнейшем сообществе писателей, я случайно запилил аж трёх ботов:
* В начале прошлого года — бота для управления знаниями за счет автоматической пересылки в топики Белого чата;
* Через несколько месяцев - антиспам на регулярках, с одним из самых развестых наборов регулярок в рунете. В итоге получилось коло 5 000 забаненных спамеров только в автоматическом режиме;
* Бота с капчей, анонс которого, кажется, стал самым залайканным сообщением в Жёлтом чате.

4. Зарегистрировался на TechWriter Days 2, где мы с коллегой зачитаем мощнейший хип-хоп (ладно, на деле мне пришлось отказаться от такой подачи информации) про линтер на основе YandexGPT в конце марта 2025 года. Ставьте лайки, приходите послушать, буду рад развиртуализироваться.

Кажется, год получился успешный. На этом всё, спасибо что читаете, до встречи в новом году!

Обзор трендов ИИ в документации (не мой)

Вечером первой рабочей пятницы приятно почитать что-нибудь расслабляющее, например мнение одного из старших технических писателей Google (судя по резюме — лид документации Google Fuchsia) на то, что принёс в эту сферу 2024 год. Обзор не то чтобы был слишком информативный, но это в любом случае лучше, чем ничего. Отдельный плюс автору за анализ своих предсказаний, данных в конце 2023 года, значительная часть из которых не сбылись.

С обзором можно ознакомиться за 10 минут, но я вынесу сюда одну ключевую мысль — пока что нет никаких признаков того, что генеративный ИИ оказывает какое-либо заметное влияние на рынок труда для технических писателей. Как и в остальных сферах, новые юзкейсы, в которых генератиный ИИ будет по-настоящему заменяться человека, обнаруживаются с трудом. Давление на рынок есть в других областях — в копирайтинге, иллюстрациях, подготовке новостей и т.д., но пока ещё не у нас.

2024 Machine Learning Review (For Technical Writers)

#чтиво

Международный день наставничества

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

1. Поблагодарить всех тех, кто доверился мне и пришел на сессию, чтобы поговорить о своей карьере;

2. Поблагодарить @ArinaBallerina, которая вовлекла меня в это дело, без предупреждения направив ко мне первого менти из числа технических писателей;

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

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

Я думал, что заведу профиль и ко мне придут люди, которым нужно будет помочь понять, насколько им подходит наша профессия, как представители других профессий смогут писать лучше, как подготовить своё первое резюме и всё в таком духе. Так вот, такого не было ни разу. Все свои сессии после заведения профиля я провёл с людьми, которым выдал бы как минимум уровень миддл, и мне ни разу не приходилось разбираться с понятными запросами вроде ревью портфолио.

В этом я нашёл для себя дополнительную ценность: решая чужие проблемы, мозг ищет самые неожиданные решения и достаёт откуда-то из закоулков памяти вещи, о которых можно не вспоминать годами. Анализировать чужую карьеру — это повод подумать и критически разобрать свою собственную, ну и посмотреть на то, как живут другие люди и вспомнить, что за пределами собственного опыта есть множество других дорог.

Для меня менторство стало ещё и отличным показателем того, как многого я не знаю или плохо понимаю, но о чём приходится говорить с умным видом. Этот факт послужил для меня толчком к давно назревшему действию — я начал нормально организовывать свою базу знаний, вытаскивая её из 8 приватных каналов в Телеграме, где она у меня до этого жила. Оказывается, структурировать знания для себя может быть даже сложнее, чем для кого-то другого, но это явно того стоит.

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

Что я читаю про документацию на английском

Катя @ushkatia поделилась списком источников актуальных знаний на английском языке. 6 хороших ресурсов, из которых я отслеживаю обновления на сайте конференции Write the Docs через ежемесячную рассылку.

Её пост: https://t.me/ringova/672

Это смотивировало меня на составление собственного списка источников, позволяющих мне держить руку на пульсе происходящего в англосфере. Они все тоже на английском и имеют одну особенность — за ними можно следить либо через RSS, либо через почтовые рассылки. Просто невероятно, что люди в наше время продолжают поставлять контент асинхронным способом, оставляющим свободу выбора времени и способа чтения.

NB: Единственным сайтом по профессиональной тематике на русском языке, который я отслеживаю, остаётся Хабр, у которого сверхгибкая настройка условий для попадания постов в ленту, которая потом еще и отправляется через RSS. Всё остальное у меня в Телеграме.

Итак, список тех, кого я читаю регулярно:

1. idratherbewriting.com

Думаю, что сайт Тома Джонсона должен быть первым в этом списке. Многие так или иначе сталкивались с его курсом по документации API, ну или с его локализованным вариантом, но на самом деле автор практически каждый месяц поставляет что-то интересное, в том числе принимая участие в публичных дискуссиях в англоязычном сообществе. Его сайт открывается в России не у всех провайдеров, так что можно готовиться использовать VPN.

2. thisisimportant.net

Сайт писательницы Sarah Moir (Splunk, Snowflake, etc). Интересен практически каждый пост, но мой главный хит (породивший дискуссию с Томом Джонсоном) — Docs as code is a broken promise. Читать и перечитывать тем, кто думает, что точно знает реалии работы с docs as code с организационной стороны.

3. passo.uno

Fabrizio Ferri Benedetti первый писатель из англосферы, живущий за пределами США — в Барселоне. У него хорошие навыки программирования и он занимается этим в свободное время, что отражается на его постах. Я бы сказал, что в равной степени они посвящены docs as code, программированию, UX и карьере в общем смысле. Любимый пост выбрать сложно, но для разнообразия пусть будет Technical writing is not a dead-end job, it's a landing pad

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

1. ffeathers.wordpress.com

Сайт Sarah Maddox, проработавшей десять лет в Гугле и запускавшей программу Season of Docs. Последний пост был про то, как она на время бросает айти и уехала кататься по Австралии, но я всё ещё жду новых постов, потому что раньше они были превосходными: Financial impacts of good or bad communication

2. docsbydesign.com

Bob Watson писал документацию задолго до моего появления на свет. Я подписался на его блог после короткого, зато прямо-таки программного поста: Proving and defending the value of technical writing, again

3. technicalwriting.dev

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

А что у вас есть из интересных источников?

#чтиво

DeepSeek: смотрим трезвым взглядом [1/2]

С момента релиза DeepSeek я прочитал огромное количество фактов и мнений о том, что это за модель, как ее делали и как ее релиз изменит мир машинного обучения. От одного уважаемого канала я даже отписался, увидев мнение, составленное на основе рерайтов новостей и вбросов в Твиттере. Хочу зафиксировать несколько мыслей по поводу этого релиза, противопоставив их популярным тезисам:

DeepSeek был сделан трейдером-энтузиастом в свободное время

DeepSeek — это исследовательская лаборатория китайского хедж-фонда High-Flyer, появившаяся в 2023 году. Фонд специализируется на квантовом трейдинге, то есть на торговле с использованием сложных статистических моделей, в том числе моделей машинного обучения. То есть это не случайные люди в индустрии. В 2021 году они создали свой первый суперкомпьютер, который через год заменили вторым, более мощным. Нужно сказать, что сама торговля конкретно с помощью алгоритмов машинного обучения не всегда проходила успешно, но в целом результаты фонда как такового более чем приличные.

Стоимость создания DeepSeek составила 6 миллионов долларов

Не будем говорить о том, что High-Flyer, как это принято в HFT, нанимал лучших и платил им огромные деньги. Скажу лучше, что еще в 2021 году основатель хедж-фонда увлекся генеративным ИИ и стал скупать лучшие на тот момент чипы NVIDIA. Обратите внимание, что начало этого процесса совпадает с годом появления их собственного суперкомпьютера, и я уверен, что скупка не прекратилась после введения санкций на поставку передовых чипов в материковый Китай. Так вот, упомянутая цифра в 6 миллионов — это расходы на обучение одной из предыдущих версий (V3), а DeepSeek прогремел со своей «рассуждающей» моделью R1. 6 миллионов долларов не включали затраты на дообучение R1, не учитывает рабочее время специалистов (минимум 50 человек), не включает стоимость железа и всего прочего.

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

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

В день релиза рынок отреагировал резко — капитализация крупнейших игроков индустрии упала на 5-10%, DeepSeek взлетел в топы сторов. Все задавались вопросом «Что же будут делать гиганты и игроки поменьше, если энтузиаст из гаража за 6 миллионов долларов делает модель, которая распространяется бесплатно, и с открытыми весами и рвёт топовых конкурентов». Тут нужно держать в голове несколько вещей:

1. Это не первая бесплатная модель с открытыми весами, уже есть как минимум Llama и Mistral. Мы кстати продаём доступ в том числе и к Llama в сервисе Foundation Models.

2. NVIDIA постфактум стала одним из бенефициаров создания DeepSeek, так как с помощью именно этих чипов модель дообучалась. И с ростом эффективности и удешевлении обучения нужно будет не меньше чипов, а больше. Этот эффект стабильно воспроизводится для всех востребованных ресурсов, в литературе известен как Парадокс Джевонса.

3. DeepSeek R1 всё ещё создавался на деньги, который хедж-фонд вливал в свою лабораторию. Но даже с их выдающимися оптимизациями (есть полный список, но вряд ли кому-нибудь они действительно интересны) дальнейшее развитие модели и поддержка соответствующей инфраструктуры скорее всего будут стоить больше, чем может себе позволить даже действительно успешный фонд. А в Китае у квантовой торговли как таковой сейчас непростые времена, подробнее см. https://t.me/nonamevc/1224

#искин

Продолжение ниже ↓

DeepSeek: смотрим трезвым взглядом [2/2]

Мой опыт

Мне было лень проводить полноценное сравнение, особенно в тех аспектах, где рассуждающие модели проявляют себя по-настоящему хорошо. Но я задал несколько контрольных вопросов ChatGPT o1 и DeepSeek (в режиме чата). Результаты не то чтобы сильно отличались, но это, конечно, повод сделать комплимент DeepSeek. Всё-таки выпуск рассуждающей модели такого уровня по такой цене (для API) с открытыми весами — это действительно серьёзное достижение. Представители OpenAI кстати заявили, что обнаружили доказательства использования дистилляции через API OpenAI — техники, при которой одна модель учится на основе данных другой. Впрочем, до официальных обвинений дело не дошло.

Что же касается обычных запросов, связанных с написанием кода, то мой привычный Claude 3.5 Sonnet продолжает демонстрировать лучше подходящие мне результаты, тут я провел чуть более серьёзное сравнение. Я попросил DeepSeek и Claude написать код для относительно простого юзкейса: отправка данных через HTML-форму, обработка данных в бессерверной функции в качестве бекенда, отображение результатов на странице рядом с формой. Код DeepSeek явно уступал в наглядности, и я не был уверен, что все части цепочки заработают с первого раза. К тому же Claude предложил улучшения и дополнителнения, о которых стоило подумать.

Выводы

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

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

#искин

Текст без опечаток любой ценой, но бесплатно

Я наконец закончил статью о внедрении спеллчекера CSpell, работать над которой начал почти год назад. Немного не дотянул до 50 000 символов, пришлось немного порезать статью в финальной редакции.

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

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

https://habr.com/ru/articles/902236/

#docsascode

Пятничное чтиво 1

Fabrizio Ferri Benedetti: What's wrong with AI-generated docs.

Запускаю новую рубрику, надеюсь что регулярную. Есть много интересных текстов, которые так или иначе относятся к наиболее сильно интересующим меня областям — технологиям, управлению знаниями и организации процессов, и этими текстами иногда хочется поделиться.

В первом посте этой рубрики статья Фабрицио Ферри Бенедетти, в которой человек с впечатляющим опытом смотрит на явление, которое многих пугает. При этом я точно знаю, что даже понимание всего, что описано в статье, не предотвратит массовое распространение слоп-контента еще и под видом документации. Но ознакомиться и осознать минусы такого контента стоит как минимум для того, чтобы побеждать незнакомцев в интернете в спорах.

Некоторые мысли, которые мне особенно нравятся:

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

* Документация даже у новых LLM получается похожей на старые README. Применение жестких правил для управления результатами стороны модели возможно, но это не просто.

* Документация, созданная таким образом и не проанализированная человеком, может содержать всевозможные галлюцинации, из-за которых она не может быть источником истины.

* Документация — это не просто набор фактов, это engineered experience, кто-то должен подумать о пользователе и о том, как он воспримет написанное.

В общем, советую.

#чтиво

Пост об использовании спеллчекера CSpell в CI на GitHub

GitHub Action для запуска CSpell в CI

В недавно упоминавшейся статье для Хабра, посвященной использованию CSpell, я не описал одну довольно важную вещь — как именно запускать проверку орфографии в CI-пайплайне. У меня был только черновой код, который демонстрировал нужный подход.

Я собрался с силами и написал настоящий Action, который позволяет полноценно работать с CSpell на GitHub. В новой статье я рассказал немного про требования, ограничения и нюансы реализации.

P.S. А прямо сейчас на канале QFE идет курс, посвященный основам GitHub Actions, к которому я приложил руку. После этого курса, конечно, нельзя сразу стать докопсом, но можно получить представление о том, как подходить к такой автоматизации.

Редизайн сайта: отказался от 11ty в пользу Zola

https://alexjameson.github.io/

Когда мне нужно было опубликовать статью о сравнении генераторов статических сайтов, я просто сделал сайт с помощью генератора 11ty и разместил там статью. Все SSG, которые я до этого использовал, так или иначе обещали минимализм в настройках и потреблении ресурсов, и для меня это было самым важным. Хотелось иметь возможность просто набирать текст в Markdown, просто делать git push и видеть результат.

Сейчас я надеюсь, что переделал сайт в последний раз. Хочу зафиксировать несколько выводов, к которым я пришел в процессе перебора разных инструментов:

* SSG для документации и для блога могут отличаться друг от друга. У многих классических генераторов есть темы, которые делают из них блог, но при этом они остаются теми же самыми инструментами со своими особенностями и ограничениями.

* Чем проще SSG для блога — тем лучше. В свободное время абсолютно не хочется разбираться с конфигурацией вещей, которые не относятся к созданию страниц или написанию постов. Но простота может быть иметь свой недостаток — невозможность обеспечить своему сайту желаемый вид. Управление сочетанием простоты и кастомизируемости — серьезная задача для создателей инструментов.

* Некоторые SSG хорошо годятся для обоих классов задач, например Hugo. Я не использовал его в финальной итерации исключительно из желания еще немного поэкспериментировать. В процессе я нашел еще много хороших решений, которые могу бы использовать, но в силу разных причин не стал.

* 11ty обещал простоту и возможность лёгкого расширения функциональности за счет плагинов, но кое-чего я не учел. В начале все шло хорошо, хотя я терпеть не могу какую-то непонятную массу в node_modules. Тем, кто давно работает с экосистемой JavaScript известно, что все это быстро устаревает и выстреливает в самый неподходящий момент. Еще в процессе работы я понял одну вещь — возможность кастомизировать что угодно предполагает необходимость принять множество мелких решений. А я не хочу принимать такие решения в свободное время — я хочу писать посты, делать git push и видеть результат.

Финальной точкой для меня стало появление ошибки в логах сборки, которая говорила об ошибке в парсинге статьи плагином для RSS, а он у меня даже не был активирован! В итоге я просто убрал фрагмент, который вызывал эту ошибку, и ...

Переписал все на последнем генераторе, который хотел попробовать. Zola написан на Rust (the only thing your customers care about is whether your software is written in Rust), при этом знание самого языка не обязательно. Как и у Hugo, для работы нужен только один бинарный файл без зависимостей. Начало работы и базовая настройка занимают минуты, нет никаких жестких требований к структуре сайта, есть поддержка CommonMark с элементами GFM. Темы также ставятся и подключаются сразу, шаблоны почти не отличаются от Liquid, а конфигурация осуществляется без магии с помощью TOML.

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

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

Пятничное чтиво 2

Arjun Panickssery: Why Have Sentence Lengths Decreased?

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

В статье, которую я предлагаю почитать сегодня, приведен статистический анализ снижения среднего количества слов в динамике. Для художественной литературы это снижение выглядит так: от 49 слов в предложении (wps, words per sentence) у Джеффри Чосера в 1400 году до 12 wps у Джоан Роулинг, а в газетах — с 35 до 20 wps с 1700 по 2000 гг. Схожая картина наблюдается во всех областях, от ежегодного обращения президента США «О положении страны» до писем Уоррена Баффетта инвесторам.

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

В общем, рекомендую интересный экскурс в историю для всех пишущих людей.

P.S. Кстати, этот пост попался мне на глаза в сообществе рационалистов LessWrong, и комментарии там традиционно стоят того, чтобы с ними ознакомиться.

P.P.S. В текстах, опубликованных на этом канале в 2025 году, в среднем было 15 слов в предложении.

#язык #чтиво

Как я выбрал Qwen в качестве основной модели

Заметил, что фактически ушла в прошлое распространившаяся в прошлом году привычка отвечать на вопрос реального собеседника копипастом ответа языковой модели. Кажется, теперь это наконец-то считается тем же, что и отправка скриншота поисковой выдачи в качестве аргумента. Хочется верить, что это следствие накопленного опыта и последующего «расколдовывания» таких технологий.

Поиск с ИИ, будь то ответы Гугла, Яндекса или Perplexity, для меня стал одним из самых частых сценариев использования. У меня даже произошел откат в этом смысле — я перешел обратно к поиску в браузере от вопросов в чате.

Но зафиксировать я хочу не это, а то, как меняются привычки, касающиеся нейросетей. С момента вирального распространения ChatGPT 3.5 я, как и большинство моих знакомых, пользовался Телеграм-ботами для доступа к разным моделям в режиме чата. Уверен, что каждый читатель перепробовал много разных, а самые целеустремленные (или просто живущие за пределами России) пользовались и непосредственно самим чатом. Напомню, что все фактически началось в ноябре 2022 года.

С тех пор почти все подобрали модели себе под свои задачи. Для кода и технических задач я давно остановился на Claude Sonnet, начал с 3.5 и остановился на 3.7, несмотря на релиз версии 4.0. Непосредственно для работы я использую YandexGPT Pro, которой могу отправлять в том числе то, что попадает под NDA.

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

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

Фактически, основной развилкой для меня был выбор между непосредственной работой с моделями, доступными в России и любым способом доступа к западным платным моделям. Выбор был сделан в пользу первого варианта, так что вариантов у меня стало не так много — YandexGPT, DeepSeek, Qwen и Mistral AI (Le Chat).

Я сравнил результаты выполнения заданий, связанных с написанием кода и редактурой текстов всеми этими моделями, и достаточно уверенно сделал выбор в пользу Qwen, и вот почему:

1. Qwen действительно быстрый, лишь немного медленнее чем Le Chat и в разы быстрее DeepSeek.
2. Приложение и веб-версия работают стабильно, а поставщик этой открытой и бесплатной модели — одна компания (Alibaba).
3. Модель открытая, так что при необходимости доступа по API я смогу воспользоваться одним из российских сервисов Foundation Models (понятно, какой выбираю я).
4. Qwen действительно хорош в работе с русским языком. Вероятно, это стало одной из причин использования весов Qwen-2.5-32B-base на этапе претрейна при обучении YandexGPT 5 (подробнее на Хабре).
5. Модель показывает стабильно хорошие результаты для всех классов задач. YandexGPT я продолжу использовать для простых задач по обработке текста, особенно с информацией под NDA, или созданию регулярных выражений, но помощь с кодом и в принципе технологическими контекстами я поручаю другим моделям. Для работы у меня также остается плагин SourceCraft Code Assistant, который я использую в VS Code с той же целью, с которой люди используют Copilot, но я не использую его в свободное время сразу по нескольким причинам.

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

Лучшая база данных фотографий, привязанных к месту

https://pastvu.com/

Как-то давно мне попадалась на глаза информация, что каждый год в интернете теряется около 0.5% информации, замещаясь чем-то новым. Я сходу не смог найти подтверждение, но интуитивно кажется, что это недалеко от истины. Ссылки ведут в никуда, бесплатные хостинги закрываются, посты в соцсетях удаляются, от некогда популярных ресурсов отворачиваются пользователи, все такое. Поэтому мне всегда нравились проекты, которые создаются сообществами и ведутся собственными силами. В этом есть некоторая гарантия, что информация будет жить дольше за счет чьего-то искреннего интереса.

Один из таких проектов — PastVU, как авторы сами пишут, это «Проект по сбору свидетельств прошлого. Взгляд на историю среды обитания человечества.». Работает он довольно просто, но эффективно — берется карта регионов на на OpenStreetMap, а к отдельным точка привязываются фотографии, которые загружают пользователи. Получается карта человеческих воспоминаний о каких-то конкретных местах.

Фотографии охватывают самые разные временные периоды, самые интересные лично для меня — оцифрованные чёрно-белые изображения позднесоветского периода. Но так попадаются настоящие раритеты, которые каким-то образом попадают к энтузиастам проекта. Охвачен фактически весь мир, но плотнее всего распределение по России. Если я правильно понял статистику, то сейчас на сайте около 2 миллионов аннотированных фото, что позволяет в том числе фильтровать изображения по конкретному периоду.

Проект опенсорсный, код выложен на GitHub под лицензией AGPL-3.0. На главной странице репозитория есть также краткая история проекта, как минимум один из основателей вам точно известен. Технические писатели могут внести свой вклад не только фотографиями, но и за счет улучшения документации, у проекта есть специальная страница, посвящённая этому вопросу.

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

Как именно ИИ угрожает профессии технического писателя [1/4]

Во-первых, меня страшно раздражает аббревиатура ИИ. В 90-е годы в переводной научной фантастике был введен термин ИскИн, и это было сделано людьми со вкусом, несравненно лучше ведь, чем безликий «ИИ».

Но есть и во-вторых. Я не особо беспокоюсь по поводу более продвинутых инструментов, которые смогут быстрее и эффективнее создавать тексты и сопутствующие материалы. Пусть ускоряют, пусть даже пишут за меня, я только за. Процесс создания и публикации контента — не самая затратный момент в работе, которому я в последние пару лет уделяю совсем все меньше времени. Меньше времени на рутину — больше времени на продуктовые задачи. Я сам пользуюсь и чат-ботами, и другими инструментами на основе нейросетей, от линтеров до первых, неуверенных экспериментов с агентами, и официальный курс в нашей компании — внедрять их как можно больше. В масштабах индустрии это сделает тексты дешевле, но я делаю ставку на то, что в итоге задокументированы будут те вещи, до которых никто и никогда не добрался бы, а качество документации будет в среднем выше при радикально меньших затратах.

Я говорю только о пользовательской документации к программным продуктам для самых разных аудиторий, вне зависимости от того, внешние они или внутренние. Документация в любом случае сама может и должна быть продуктом, решающим определенные задачи. Да, бывает документация других типов — проектная, для регуляторов и т.д., ее можно составлять для программно-аппаратных комплексов и прочих систем, но я всем этим не занимаюсь, и я не хотел бы рассуждать о том, в чем у меня нет достаточной экспертизы.

Причина моего беспокойства в другом. Мы пишем документацию для тех людей, которые так или иначе приносят деньги нашим работодателям, и привычки этих людей сейчас радикально меняются. Раньше у разработчика было, по большому счету, два варианта: изучать исходники и/или сопроводительные материалы — документацию, примеры кода, демо-примеры, вебинары, статьи. Сейчас же наш потребитель учится действовать иначе, пользуясь новым поколением инструментов. Меняется сам ландшафт сферы программной инженерии, и в следующих постах я постараюсь дать небольшой обзор этих изменений с точки зрения технического писателя.

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

#ai

Как именно ИИ угрожает профессии технического писателя [2/4]

Предыдущая часть

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

1. Открыть чат с наиболее умной и дорогой моделью и попросить проработать верхнеуровневую архитектуру. Можно до этого этапа сформировать ТЗ с требованиями и описанием системы.

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

3. Открыть любимую IDE, будь то Cursor, Windsurf, что-то от JetBrains с Junie, VS Code с Copilot, ну вы поняли. Будет создан бэкенд, база данных, все проинтегрировано и подготовлено к развертыванию. На этом шаге используется архитектурная спецификация, подготовленная на первом шаге.

4. Подготовиться к списаниям с карты и начать контролировать процесс создания кода, нажимая Tab или просто комментируя происходящее в чате.

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

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

Значит ли это, что документация становится совсем не нужна? Я думаю, что даже в озвученном выше сценарии видно несколько мест, где документация всё-таки пригодится:

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

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

* Сами модели должны откуда-то получить информацию.

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

#ai

Как именно ИИ угрожает профессии технического писателя [3/4]

Предыдущая часть

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

С той или иной долей уверенности можно утверждать, что основная задача при подготовке документации для моделей — правильно перевести ее в удобный для нейросетей формат, а не изменить ее коренным образом. Насколько я знаю по собственному опыту и по конференциям, сейчас технические писатели редко погружены в эти задачи, чаще они выполняются ML-инженерами. То есть для обучения моделей нужна та же документация, которая существовала всегда, просто подготовленная особым образом. Но насколько глубокой должна быть подготовка?

Напомню, что хорошая документация почти всегда соответствует нескольким ключевым принципам, таким как Every page is page one. Документация, которую в идеальном случае увидит пользователь, должна быть понятной, легко воспринимаемой, атомарной, а информацию в ней должно быть легко искать. Подробнее см. в статье Should you write documentation differently for LLMs?

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

Интересную попытку осмысления этого вопроса с точки зрения технического писателя я видел в другой статье, напоследок советую с ней ознакомиться: Docs for AI agents.

#ai