Feedback on Userguide

[mitsie]

I have recently developed two plugins for Calibre. I have an extensive background in Web Development and programming. Took me about a week to develop the two plugins, but I feel it could have been faster.

Just want to give a little feedback on the Documentation and my experience.

The documentation is very lacking, and I found myself repeatedly downloading other people's work to get examples of how specific features of Calibre work.

I constantly had to stack trace back through thousands of lines of code from the source code, to work out what the input and expected outputs of the abstraction-layered functions do. The documentation isn't clear enough, and not enough examples are given.

There are places both in the user guide and the code comments where terminology is ambiguous. Calibre deals with ebook readers with SD cards, it also formats code, as well as working with file formats.

format_metadata()
Does that mean "Format" (Delete) the metadata on the SD Card?
Provide "File Format" (Type) Metadata?
or "Format" (Organise) the code related to the metadata?

format_abspath()
Does that mean "Format" (Delete) the data at the absolute path?
Provide the "File Format" (Type) path?
or "Format" (Organise) the path using the os path separator?

In English, the meaning of Format can mean multiple things depending on the context. (Delete, Organise, Storage Type) When dealing with people's files and databases, making the distinction between them is of utmost importance.

Flow direction.. There are no `get` or `set` instructions before each function to tell the user the flow direction of the data. For instance, if the function names were written as `get_file_format_metadata`, this would be clearer about the flow direction, clearly explaining the exact context of the command.

There are places in the documentation where it seems like you're trying to explain Quantum Physics to your dog lol. When dealing with searching the database in the documentation, it states:

Query: This is the Query variable you send the Query to be queried?
Thats's all you get as an explanation.
No details on the type of query expected by the function, SQL string, dict, tuple, list, kwargs.
No details on what type of data the function returns?

Some of the comments in the code make no sense at all:

`isn't supported in by the obsolete library.database2. Use db.legacy.LibraryDatabase instead`

Obsolete means old, but library.database2 is the location of the "new_api" function you tell users to use. So is the new function obsolete, and do we have to use the legacy version? Because Legacy means old as well.

Just things like that bamboozled me, as none of it makes sense.

Now, after explaining the above, it doesn't take away from the great work you have done with the software. I understand it has been nearly 20 years of coding, and I understand that updating documentation on an ongoing project is a tedious task. I feel your pain.. I'm not trying to be negative or put the project down, just trying to provide some positive criticism.

There are tools out there to rewrite Python functions en mass, to better explain their understanding, dataflow and context and readability for others.

There are also tools for creating detailed documentation, using standard tools such as doc-string comments in the code to automatically build and update the documentation in multiple formats as you code.. new tools such as A.I documentation writers, etc, that are very effective. Might be worth a look at doing, when you get some time

https://www.sphinx-doc.org/en/master/

[BetterRed]

Originally Posted by mitsie

There are places in the documentation where it seems like you're trying to explain Quantum Physics to your dog lol. When dealing with searching the database in the documentation, it states:

Maybe that's to be expected==>> https://thesis.library.caltech.edu/2...vid_thesis.pdf

BR

[mitsie]

Originally Posted by BetterRed

Maybe that's to be expected==>> https://thesis.library.caltech.edu/2...vid_thesis.pdf

BR

That explains it then

[kovidgoyal]

Was this post written by an AI? It contains obvious nonsense. For example, format_metadata is documented very clearly as "Return the path, size and mtime for the specified format for the specified book". I would expect an AI to find that confusing since AI has the IQ of a 3 day old corpse, but not a human being. Similarly, there is only one new_api function in the entire codebase and it isnt in library.database2 but in db.cache.

In any case, whether you are artificially intelligent or merely unintelligent, I suggest you send some PRs improving those parts of the documentation that you found confusing. Much more productive than this farrago of nonsense.

[mitsie]

No I'm not an AI.
It's not explained clearly at all, you should know having a degree in quantum computing, anywhere that has "format" and "data" in the same sentence you proceed with caution.

You built, the software, you understand it. This forum is littered with people who constantly ask questions because the user guide is lacking..

I'm just trying to give positive criticism of the problems I see in the codebase and the documentation.

You don't want the advice. I couldn't care less to be honest.

ISO9001 the industry standard for product and service improvements is taking people's criticisms on board, gracefully.

Clearly you must get some sort of a ego trip off people asking you questions, rather than providing clear, adequate and helpful documentation for others..

I'm not going to learn and refactor a 20 year old code base am I? I've got more important work to be on with.. It's your code base..

You don't care, I couldn't care less.. so let's just leave it at that..

[DNSB]

One thing I learned during my career is you never ask the developers for more than minimal input into documentation. You need people who write documentation not programs for that job. The developers know the subject too well and, as one of my university professors was fond of saying, "It is therefore obvious..." when jumping from the first couple of steps to the conclusion leaving out any and all intervening steps. The worst part is that they don't even realize they are doing this since to them, it is obvious.

[kovidgoyal]

As I thought, you were merely trolling. Like I said, if you want to be actually constructive or productive open PRs, with actual documentation for what *you* find confusing. Don't try absurdities like a function named format_metadata() is dangerous because format can have multiple meanings.

There is plenty of low hanging fruit when it comes to documentation. For example, open db/cache.py scroll through all the functions marked with @api or @write_api or @read_api find the un documented ones or under documented ones, and improve the documentation.

If you arent willing to do any actual work yourself, then dont expect other people to do it for you.