README Restoration: When Reference Docs Fight Back

I inherited a Speech to Text project that had undergone a brutal README rewrite. The new version was sleek, minimal—a polished marketing page. Problem: users were lost. They couldn’t find how to configure the app, build the EXE, or install models manually behind restrictive ISP blocks. The reference documentation had been sacrificed on the altar of simplicity.

The commit message was blunt: “previous rewrite cut too much.” I had to restore what marketing had removed.

The work wasn’t glamorous. It meant reverse-engineering what sections had existed, then rebuilding them properly. First came the Usage section—tray menu items, Settings window tabs. These aren’t flashy, but they’re how people actually use software. Then the config.json reference. Not a tutorial. Not “here’s an example.” A complete field-by-field breakdown for v2.0.9, with actual values users would need.

The tricky part was the manual model installation. Users in certain regions can’t reach Hugging Face directly. I had to document the fallback: cascade’s Whisper-AI repo and ONNX diarization files, with mirror URL tables showing each option. That meant testing the URLs, verifying they still worked, and understanding why someone might need them in the first place.

Then came the building and release workflow. The publish_cuda.sh script wasn’t secret sauce—it was operational knowledge that belonged in the docs. Same with the project structure tree, which had drifted. We’d dropped vosk and T5, added pyannote_onnx_lite, wespeaker_onnx, hallucination_filter, text_normalizer, crash_reporter. The structure needed to match reality.

The troubleshooting section got expanded too. A note about cascade fixing Whisper hallucinations. Tips for diarization. A mention of debug_save_audio for when things fail silently. These come from experience—from users hitting walls and needing answers.

What struck me was the tension between two legitimate goals: marketing wants a clean, inviting introduction. Users want a reference manual they can actually use. The solution wasn’t choosing one or the other. It was structure. Marketing intro at the top, then reference docs below. Both EN and RU rewritten in parallel to keep them aligned.

By the end, the README was longer, but functional. It told potential users what the project was, then showed them how to actually use it. Sometimes restoration beats simplification.

And if your strings ever get corrupted in the bar, at least check if they’re null-terminated. 😄