User Guide

[dannysmith]

I've noticed a number of issues and discussions being opened where the solution is "it does that already" or "enable this setting". This is a sign we should have some user-facing docs, probably on https://handy.computer. This is quite a different thing to the developer-facing docs mentioned in #409.

It's probably not worth doing this until the work being discussed in #103 has been done.

My initial thoughts are that we should keep this simple, and broadly cover the following:

• Basic Usage & Configuration
• Transcription Models
• Post-Processing
• Advanced Configuration
• How To Guides (eg. How do I add a space after the transcription, how do I make it transcribe into English etc etc etc)
• Debug Mode, Experimental Features and settings_store.json

We should 💯 try to make this useful while being as un-brittle as possible – minor changes to the UI and/or features shouldn't always require changes to the userguide.

The easiest option here is to have a userguide/ directory in this repo containing markdown files & images, and then build out a single HTML page in some super-simple way, deployed via a GH Action. Reaching for something like starlight feels like overkill, but maybe not? If we wanna pull changelog entries from the GH Releases, or handle multiple languages etc it might be better to have a more robust build system?

Opening this discussion to collect thoughts for now ( cc @cjpais )

[cjpais]

Yeah this is desperately needed I think haha, I often type nearly the same message mainly because of lack of documentation.

I'm generally pretty happy with Astro/Starlight. Potentially we can migrate the actual handy.computer website here to turn it into a monorepo. The site itself is already astro I believe, and either we can just make a collection or use something prebuilt. I don't have much preference at the moment as long as it ends up being functional and maintainable.

I think the monorepo would have the benefit of GitHub actions being able to have much better visibility into everything, and be able to trigger updates on the site for releases, as well as potentially things like changelog generation and even docs updates if necessary. I think and LLM action to do that would be massively helpful personally

Ooh: also regarding the debug menu, I'm wondering at what point there is a 'power-user' toggle or similar which enables an 'experimental' tab instead of debug. Where debug really gets left to debug features. And experimental more cleanly is a collection of random stuff. I'm almost okay having experimental be enabled by default as well, however I know some apps like LMStudio let you choose your level (User, Power User, Developer) which might be appropriate here as well.