Something is way off

[bill@bill.net]

Sorry to say, but I find the main Calibre site hard to follow -- just strange.

I only post because this is so unusual... there is no good frame of reference for navigating (in the usual sense -- give me some screenshots, some download links, etc... )

Maybe I will revisit the site when I have more open-minded frame and some extra time/patience.

Not intended to be cutting, only giving feedback.

[Worldwalker]

I just went back to the calibre site to see what had changed for the worse. It still looks the same to me -- complete with a big "DOWNLOAD CALIBRE" button and a download link in the top navigation bar. The demo section still has the screenshots and videos. What can't you find?

[DoctorOhh]

Welcome to Mobileread.

Originally Posted by bill@bill.net

Sorry to say, but I find the main Calibre site hard to follow -- just strange.

Can you be any more vague? In case you are going to the wrong site here is the link to Calibre's site.

Originally Posted by bill@bill.net

I only post because this is so unusual... there is no good frame of reference for navigating (in the usual sense -- give me some screenshots, some download links, etc... )

Go to the main site and click on the help tab. You will find the manual, FAQ and tutorials on this page. Maybe try the big Download tab to find, I don't know, download links?

If you have any specific questions just ask.

[Lady Fitzgerald]

Uh, guys? I have to agree that the calibre site is not the easiest to follow for a non-geek (like me, for example). I would be hopelessly lost without this forum (meaning there's hope for me?). But, considering how quickly calibre is evolving, it's understandable, especially since it means more effort is being put into developing calibre than the website. At least the OP tried to make the comment non-malicious.

[DuskyRose]

Originally Posted by Lady Fitzgerald

Uh, guys? I have to agree that the calibre site is not the easiest to follow for a non-geek (like me, for example). I would be hopelessly lost without this forum (meaning there's hope for me?). But, considering how quickly calibre is evolving, it's understandable, especially since it means more effort is being put into developing calibre than the website. At least the OP tried to make the comment non-malicious.

Yeah, I have to agree. It's really not new-user friendly. Heck, it's really not old-user friendly, as I have to come here and look up stuff a *lot*.

Most of the things I look up tend to take me to pages with programming language or command line stuff.

Last thing I couldn't figure out how to keep the Sony from sorting on Series information. Once it was pointed out to me, easy to change. But nothing I could find on the web site even got close to pointing me to the answer. I got it here.

And even now, I'm curious as to what the "Use Sub Directories" under "Customize Sony Device Interface" means. (Under Device Interface Plugins) I have no idea what that does, so haven't touched it. Can't find any information on it.

I may love/need what it does, but I don't know and probably won't until I ask here. This should all be at the web site, frankly.

[Manichean]

Originally Posted by DuskyRose

[...]

And even now, I'm curious as to what the "Use Sub Directories" under "Customize Sony Device Interface" means. (Under Device Interface Plugins) I have no idea what that does, so haven't touched it. Can't find any information on it.

I may love/need what it does, but I don't know and probably won't until I ask here. This should all be at the web site, frankly.

I think the problem, if there is one, is that the manual is sort of like a first introduction to Calibre along with a few tutorials for selected more advanced stuff. There is no single documentation for everything. Though, to be fair, the help page links to this forum, and I've yet to see a request for help here go unanswered.

Edit: I don't know if there is an effort to develop the manual to encompass every single option Calibre offers. I don't even think that's necessary or practical. I do, however, know that Kovid welcomes useful additions to the manual.

[chaley]

From this developer's viewpoint:

Writing documentation is hard. Bad technical writing takes time. Mediocre technical writing takes a lot of time. The time required by good technical writing can easily exceed the time taken to do the programming. The work isn't fun (and I do this to have fun). We get hassled over matters of style, clarity, organization, and typography, and sometimes accuracy. What we do write seems to be ignored, although I admit it is hard to know who *didn't* ask a question because of the docs.

We aren't dealing with contracts acceptance clauses; there is no commercial reason to write it.

For me, there are only two motivations to write documentation: to test the new stuff (do I understand what I am doing enough to describe it logically?), and boredom with coding. The first case is rare, and in the second case I would rather read.

I am mildly surprised that more people don't volunteer to do documentation. It requires no python/programming skills, can be done incrementally, is a good way to learn, would be actively supported by people, and is a fine way to contribute to the project.

[DuskyRose]

Originally Posted by chaley

I am mildly surprised that more people don't volunteer to do documentation. It requires no python/programming skills, can be done incrementally, is a good way to learn, would be actively supported by people, and is a fine way to contribute to the project.

Probably because we're afraid that what we wrote would be wrong, and cause a lot more problems.

Even though I've used the program for a while, it was even hard to ask a question, because I didn't have the right words for the right process I was trying to ask about. So I had to explain what I was looking at more than once, because I didn't know what everyone else called that feature.

I try to point a lot of people toward Calibre, but do have a problem with a lot of questions about devices I don't have, and processes I've never tried myself. (For example, I'm happy with the font size on the Sony, so haven't tried all the features in the bulk convert options yet.)

So when asked, I try to find the answer here, or point people here. But as it gets more features it gets more complicated. And the answers get harder to find.

I think it would help more if the people who contribute to the program do the documentation on their own bits and then have it collected on the web site. The person who wrote it should be able to explain it.

Such as that feature from the Sony. A small note at the site might help, or something at the web site. You really have to do a lot of digging to find out the barest clue to some of this stuff.

And I've junked up whole libraries in the past by playing around on my own. I'm really leery of doing that again. So experimentation is pretty much out unless I do find that clue. Somewhere.

[silasgreenback]

Originally Posted by DuskyRose

And I've junked up whole libraries in the past by playing around on my own. I'm really leery of doing that again. So experimentation is pretty much out unless I do find that clue. Somewhere.

While I haven't mastered using Calibre all the way and am not the "savviest" guy around, experimenting on one book at a time until it does what's needed has been the best way of using Calibre in my experience.

When it comes to learning anything about bulk converting, limiting it to two books is probably the safest way of trial and error.

[DuskyRose]

Originally Posted by silasgreenback

While I haven't mastered using Calibre all the way and am not the "savviest" guy around, experimenting on one book at a time until it does what's needed has been the best way of using Calibre in my experience.

When it comes to learning anything about bulk converting, limiting it to two books is probably the safest way of trial and error.

Yeah, it would be best to do a few at a time. But that only really works if the result is something you can see right off. Sometimes the results may not show up until later, when you've gone back to doing business as usual.

For example, how to change the naming structure of a file sent back to disk was pretty easy to see the results, but how to go about it wasn't clear at all. Yes, I could restructure the name of the test file and see how it all came out, but even after playing with it I didn't learn what I was doing or what it all meant. Lucky me, I finally found someone on the forums who wanted their file names in the same format I did, and copied his 'code'. I never could find anyplace that explained it all so I could have figured it out myself. If I ever want to change it, I'll be back at square one. With no idea how it works even though I can play with it and see the results pretty much endlessly. Not so helpful.

As for the other thing, I have 2,437 files on the main memory of my Sony. I have no idea what the "Use Sub Diretctories" means. Will I need to empty out my Sony to see what changes it makes? Do I then look under "Home" "Applications" or "Settings"? How long do I mess with it just in order to find out what it does?

And I'm not sure what "Upload Seperate cover thumbnails for books" will do either. Or the "Refresh Sepearte covers when using automatic management". I'm not using thumbnails on the Sony, I just want the book title. Would this save space? Make the thumbnails work differently than they do now? What would be the advantage to clicking that check box?

Why does the author of that bit assume I understand what they're offering, and where do I do to find out, and how much experimentation am I willing to do?

So much easier if I know where to go just to look up those small things. And I'm sure people on the forums get tired of answering the same questions over and over.

[chaley]

I know I shouldn't be writing this, but I am annoyed by what seems to be an attitude that I am required to do work for you to accomplish things that are of zero interest for me.

Originally Posted by DuskyRose

... Lucky me, I finally found someone on the forums who wanted their file names in the same format I did, and copied his 'code'. I never could find anyplace that explained it all so I could have figured it out myself. If I ever want to change it, I'll be back at square one. With no idea how it works even though I can play with it and see the results pretty much endlessly. Not so helpful.

Perhaps the manual page http://calibre-ebook.com/user_manual/template_lang.html will help?

Why does the author of that bit assume I understand what they're offering, and where do I do to find out, and how much experimentation am I willing to do?

The author of that bit, me, was responding to particular problems that people were a) having and described accurately in forum posts, who b) helped work out what the problem exactly was, and who c) helped test the solution. It was a challenge, and the people raising the point were very willing to participate, to the point of providing mouse-hover tooltips further explaining what the options do.

I have no interest in how much experimentation you are willing to do, and only peripheral interest in whether you figure anything out. I do calibre development because I want to, for whatever reason I have at that moment. I am under no obligation to do work to satisfy your or anyone else's needs.

[DiapDealer]

I think it would help more if the people who contribute to the program do the documentation on their own bits and then have it collected on the web site. The person who wrote it should be able to explain it.

I think others should be responsible for documentation. The developers are already doing their bit and I don't expect anything else from them -- although I think the help we do get from them by way of this forum is prompt and frankly way above and beyond what should be expected from people who basically work for karma.

I'm not trying to hassle anybody here, but if you find the documentation lacking:
a) deal with it.
b) improve it.

This forum is the help section. If people refuse to ask here... then they can't be helped.

[DuskyRose]

Originally Posted by DiapDealer

I'm not trying to hassle anybody here, but if you find the documentation lacking:
a) deal with it.
b) improve it.

This forum is the help section. If people refuse to ask here... then they can't be helped.

I am dealing with it. I use Calibre all the time. The parts I understand. Since there's no 'Undo' button that I know about, I try to be very careful I don't create a mess I can't repair.

And how would I 'improve' the documentation when I don't really understand 1) what to call some of the terms, 2) All the ramifications of what they do?

Won't people who don't really know how parts of the program work just make things worse?

Don't get me wrong. Love the program. But it does lack in documentation on all it's various resources. I do think that's a shame, but as a newbie, I don't see that I can help much.

I can't document what I myself don't understand. And I don't know enough about a lot of it to help anyone out. I'd just like an easier place to go look things up and find out for myself.

[silasgreenback]

Originally Posted by DuskyRose

Won't people who don't really know how parts of the program work just make things worse?

Ummm...keep the original right where it was before you copied it to Calibre?

Be positive about learning?

Don't manipulate +2000 files at once?

[phenomshel]

Hmm. Well, maybe I'm missing a point here. But what is this forum if not "documentation"?
I can't name another piece of software that has this level of support. If we don't understand something by reading the manual (which has happened to me more than once), we come here, we ask, and someone is usually nice enough to explain in words of no more than two syllables what we need to know (at least if we ask politely). Admittedly, the manual is written in techspeak. But I know from experience how very hard it is to reduce jargon or programming terms into something a layperson understands. You get used to thinking of something in certain terms, and it's very hard to go back and "retranslate" it in your mind.
Agreed...someone needs to write a nontechy newbie user manual. But that someone does NOT need to be the developers, IMHO. I actually had one started, screenshots and all and then I found a link to someone else's version and decided it was better. No, I have no idea where it went, now.