Kovid,
Yes, you can find a lot info in the manual. The problem is, that you need to find them and interesting things for professional user are not in a compact form available. In addition for a lot of things a reader maybe became maybe a hind but no idea why it is usefull.
Check spelling (discussion) is a good example. Program what start as an native "English" development have often problems with hyphen word constructs in foreign languages like in German or even in for technical documentations. You find a really nicely way to get that done with user defined dictionaries. This not only with one additional dictionary, you can define as much as a user need, you can link them to languages and use it with one document. That is an important feature for professionals and an unique point of your editor. You will find these kind of information and usage only somewhere in forum discussions. Point these things from time to time out. Some of these hints I can find sometimes in a thread or as a small update description. A couple days later it is forgotten.
What I am missing (guess it is not only me) are such things like why is an feature so important and for what was it intend to use. Like the colorizing/highlighting of syntax. If I'm right, you mentioned this feature in the manual, but there is no explanation how to setup and use this. But I know, there was a detailed discussion about the feature in a thread long time ago when you start the development for it.
To understand me well, it is not criticizing you or the manual. That's something what came up mostly every week if not experienced people ask for help for calibre's editor in a "day to day" usage. calibre is not alone with this. Sigil have the same issues.
I am completely with you, a document what came with a flavor like "I do it in a better way" comparison is absolutely the wrong way (I forgot to mention that in my last post). But a brief description of features and functionalities and their benefits is needed for everyone who like to use tools in a professional way. Peoples who really spend time with these kind of tools will be capable to make a differential decision about at what point it will be a benefit to use tools for different needs.
As BetterRead points out "Writing documentation has always been a thankless task". Indeed, that's true - especially for tools like calibre what grows up every day. A similar thing to Sigil these days.
Maybe a good idea, to combine
calibre tips and tricks and videos a bit closer together. There are also a lot of people who did not know about this resources
Anyway, calibre and Sigil are sophisticated tools and peoples who are not capable to recognize this, have in my view some knowledge deficits.