What areas of calibre's documenation need improvement?

[Halo]

I will be working on improving calibre's documentation during the next six months, mainly as an effort to "scratch my own itch." I like to take notes when I learn things and calibre's open-source nature allows me to channel what I learn back into the official documentation.

I would like to hear from other users, particularly non-technical users, about which areas of calibre need to be better documented. I will do my best to improve those areas of the documentation.

• Is there an area of calibre that is poorly documented or not documented at all?
• Are there explanations in the documentation that are too complex or simple?
• Do you want more screenshots?
• Would tutorials and walk-throughs help?
• Etcetera...

Please note: I don't intend for this thread to be a place to find help about an issue you have with calibre. It's also not the right place to discuss making calibre's user interface more intuitive. I merely want to document the program as it exists right now and use this thread as a to-do list as I work on the docs. Also, don't expect improvements overnight. I'm doing this in my spare time as I learn and explore all the facets of the program.

[unboggling]

Hi Halo. I have a technical background but even so if I recall correctly I stumbled in the first week or two because I needed to see practical examples at the level of absolute beginner to get started but had a hard time finding them at that level. Maybe they exist and back then I looked at the wrong docs or something, and I didn't read the docs very carefully back then. But I remember feeling overwhelmed by the amount of documentation, and the number of experience/technical levels it applied to.

Edit: Also I was thinking possibly the assumptions technical people make coming in to calibre as new users might actually get in their way like it did in my case. Don't know if I can generalize that. But I was *assuming* that non-technical users might have an easier time learning.

[Bertrand]

Originally Posted by Halo

• Do you want more screenshots?

Yes. With tutorials and walk-throughs.

Originally Posted by Halo

• Would tutorials and walk-throughs help?

Yes. With screenshots.

[Manichean]

I'd planned to edit the regular expression tutorial to the state of the one in the forum, however, it's way down on my todo list. If you care to do that, it'd be really appreciated. Also, suggestions for improvements are always welcome.

[theducks]

Originally Posted by Halo

I will be working on improving calibre's documentation during the next six months, mainly as an effort to "scratch my own itch." I like to take notes when I learn things and calibre's open-source nature allows me to channel what I learn back into the official documentation.

I would like to hear from other users, particularly non-technical users, about which areas of calibre need to be better documented. I will do my best to improve those areas of the documentation.

• Is there an area of calibre that is poorly documented or not documented at all?
• Are there explanations in the documentation that are too complex or simple?
• Do you want more screenshots?
• Would tutorials and walk-throughs help?
• Etcetera...

Please note: I don't intend for this thread to be a place to find help about an issue you have with calibre. It's also not the right place to discuss making calibre's user interface more intuitive. I merely want to document the program as it exists right now and use this thread as a to-do list as I work on the docs. Also, don't expect improvements overnight. I'm doing this in my spare time as I learn and explore all the facets of the program.

I find the organization hard to deal with (and I am of an example of the best users guide to compare to. Later, when I remember ).
1) Label all topic sections Basic or Advanced. Provide a 'Hide Advanced (body only, so they can tell there is more...)' (use a cookie to remember button state)

2) One topic per page (KIS (visually) as to not overwhelm), with a see also section at the foot for commonly related items. Ex getting books onto your device: You have 3 different methods, with control options that are related.

3) lots of examples (cut and paste code snippets )

[kovidgoyal]

One thing that has been on my TODO list for a while is providing a decent search. This requires doing some indexing of the page contents so that matches in titles/subtitles are returned first, followed by matches in body text. The current search uses google, which is less than optimal.

Of course, doing this will require hacking with sphinx (the system used to generate the documentation and javascript to implement the search logic).

[unboggling]

Just thinking out loud. Hypothetically:

Let's say I'm not very familiar with computers and the internet, someone gifted me with a Reader and my 8 year old son helped me download and install calibre because he heard about it at school. But now what do I do? How should I actually use calibre? I need to learn more first. I notice the Quick-Start Guide. I start reading it. The introduction makes sense but a lot of the rest sails over my head - such as: Formats? Oh, no, that format thing looks like computerGeekTalk. That's beyond me. So I stop reading it. My son helps me find the calibre website. Oh no, those help documents are beyond me too. Even the tutorials.

What do I need to learn first? [I don't know enough yet to ask the right questions or where to ask them, but this is what I really need to know as early as possible:]

1. How are eBooks different than paper books? Do I need to deal with eBooks with a different attitude about them than paper books? Different strategy than with paper books?

2. What are the recommended strategies for my overall use of eBooks?

3. What are the recommended ways of obtaining them? How do I learn how to browse the internet? What are the best vendor sites to browse? What vendors should I choose, given where I live?

4. What are the ways of putting eBooks on my brand of reader either directly from vendor or with calibre?

Something that answered basic questions at a level I could understand would be nice to find. Beginners Guide to eBooks or something like that. And also maybe a Beginner's Introduction about how to find a webby thing - what do they call that? Oh, web site - thanks.

Nothing like that in my brand new calibre library. I wonder why not?

If I were computer-savvy like my 8 year old, maybe I could find something like that. I know what I'll do, I'll ask him to find it for me.

No luck. And he's a genius. Oh how I wish I could understand all that stuff. Sigh. Guess I'll stick to paperbacks for awhile until he learns what I need to know.

[theducks]

Mr. Boggled

IMHO #1 and #4 are Calibre issues and should probably be part of the Quick start guide 'Forward'

#2 I agree, e-books are not much use propping up a broken leg of a couch

#3 The simple answer is MR
Buying a e-book is no different than buying a can of soup. You avoid buying those that leave a bad (DRM) taste. It is the Manufacturers job to support 'How to use' brand-X. It is our job to help users with cheaper/better alternatives
They still need to know how to operate their chosen device.

[unboggling]

@theducks,
Heh.
OK, assume I have enough internet competence to get to MR, with the help of my little genius, such a smart and helpful boy! Now where do I go. What do I read first? Maybe I find the wiki ebook intro. That helps me learn things pretty well.

But maybe I don't.

My main point is this. Maybe it would be useful for some brand-new users to see something like the wiki introductions to various subjects packaged up into a book that arrived in their library along with QuickStartGuide. Very introductory to various eBook subjects.

I'm suggesting not to assume any level of competence in anything. Provide the info just in case. I remember lots of people got gifts of readers last Christmas. Calibre downloads increased. There may be a large number of such people.

[theducks]

Originally Posted by unboggling

@theducks,
Heh.
OK, assume I have enough internet competence to get to MR, with the help of my little genius, such a smart and helpful boy! Now where do I go. What do I read first?

The Device forum for Your device Brand. Read any stickey's first.
Then hop on over to Calibre forum, Again: Read any stickey's in the main section first (and in the specific section you choose from the topic description).

Note: I am assuming Calibre was successfully installed by the 8 year old

[unboggling]

oh yes, the darling is very competent. But I hate asking him to do things like that for me. It makes me look like a fool, and that's not good for a parent to get in the habit of.

The easier the path to the learning, the more chance I'll trod that path.

The better things are explained in plain language even a less competent 8 year old would understand, the more chance more people will understand.

[unboggling]

Oh, my library has 1 book. It looks so lonely all by itself….

Oh, it would be so convenient if it had friends….

(Immediately at installation, with user having to do nothing except learn how to use the viewer.)

[unboggling]

Promote open things? Promote counters to vendor lock-in? Explain DRM things?
Does calibre or MR want to promote such things?
(just rhetorical questions)

Now I notice DRM is explained in QSG. But my hypothetical user had given up before that.

[Barbara1955]

I use it But its HARD! But mind you I only have a 6th grade edu! In my 50s UGH Samples & Simple would be nice for this old fart!! I know if I could understan the "Plugins" I most likey use them! Cripe I dont even know that "Plugins" mean!!!

[unboggling]

Help button takes me directly into the calibre manual. My hypothetical user was overwhelmed by the manual too and never got as far as the link in QSG. (Edit2: May not even know that if it's blue and underlined, to click the link.) As alternative or in addition to the Beginner's Guide to eBooks idea, how about a Help menu choice that goes straight to the MR wiki page? New to eBooks? - Go here.

Edit. New to the internet? Go here. Learn to Find Things on Internet: Go here.