Блог

Как README потерял справочник и вернул его обратно

Три месяца назад в проекте Speech to Text произошла история, которая напомнила мне, почему техническая документация — это не маркетинг. Всё началось просто: кто-то решил переписать README, сделав его более дружелюбным и компактным. На первый взгляд, идея имела смысл. Один-пейджер вместо стены текста — казалось, это сделает проект более привлекательным для новичков. Но забыли про опытных пользователей, которые полагаются на справочник. После публикации v2.0.9 в наш репозиторий начали поступать вопросы. Где конфиг? Как настроить модель вручную? Что делать, если Whisper начал галлюцинировать на русском тексте? Ответы были в коде, в issues, в старых документах — но не в README. Выяснилось, что при переписи выпало всё самое важное: раздел о конфигурации с примерами `config.json`, инструкции по сборке EXE и публикации релизов, таблицы зеркал для скачивания моделей из Hugging Face. Последнее особенно критично для тех, кто находится за корпоративными фильтрами или в странах с ограничениями: справочник содержал адреса альтернативных репозиториев, включая cascade's Whisper-AI и ONNX дарирующие файлы. Пришлось восстанавливать. Я прошёлся по старым версиям, собрал разделы про использование (пункты меню трея, вкладки Settings), про переопределение конфигурации через реестр моделей, про структуру проекта с новыми компонентами v2.0.9 — pyannote_onnx_lite, wespeaker_onnx, hallucination_filter, text_normalizer. Добавил troubleshooting с советом по Whisper hallucinations и tips по дарирации, упомянул debug_save_audio для отладки. Главное понимание, которое пришло в процессе: README — это не маркетинг. Это справочник, который пользователь открывает на шестой минуте ночи, когда в production что-то сломалось. Он не ищет вдохновляющего слогана, он ищет таблицу, точный пример конфига или команду для отладки. Вводная часть может быть красивой, но справочные разделы должны быть полными и точными. Итог: вернули всё, что было. Теперь README одновременно красивый и полезный — маркетинг в начале, справочник в конце, both на русском и английском. 😄 Совет дня: перед тем как обновить Rails, сделай бэкап. И резюме.