View Full Version : Something is way off


bill@bill.net
01-18-2011, 12:58 AM
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
01-18-2011, 01:21 AM
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
01-18-2011, 01:28 AM
Welcome to Mobileread. :)

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 (http://calibre-ebook.com/).

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
01-18-2011, 11:19 AM
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
01-18-2011, 12:36 PM
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
01-18-2011, 12:59 PM
[...]

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
01-18-2011, 02:40 PM
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
01-18-2011, 02:49 PM
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
01-18-2011, 03:05 PM
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
01-18-2011, 03:22 PM
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
01-18-2011, 03:43 PM
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.
... 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
01-18-2011, 03:48 PM
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
01-18-2011, 03:54 PM
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
01-18-2011, 04:08 PM
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
01-18-2011, 04:12 PM
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.

DuskyRose
01-18-2011, 04:14 PM
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?

I meant in writing the documentation to add to a web site, or giving advice on how to do something with that part of the program to someone else.

I can, and do, help out people trying out Calibre for the first time at another site, someplace you really wouldn't expect there to be a forum about it, but I try to be careful I don't tell anyone to do anything I'm not 100% sure about. Especially if on anything other than the same device I'm using.

Who else would know to explain exactly what that bit does better than the programmer themselves?

DiapDealer
01-18-2011, 04:20 PM
I am dealing with it. I use Calibre all the time. The parts I understand.
Have you contributed documentation for the parts you do 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.
Create test libraries to experiment with. I do this all the time. I butcher things up royally, and otherwise figure out exactly what NOT to do in my experimental little sandbox. If I can't eventually figure it out, I come here and ask very specific questions... to which I generally get prompt and very specific answers.

itimpi
01-18-2011, 04:30 PM
New users can contribute a surprising amount if they want to put in the effort! New users are the ones who are coming to Calibre without too many pre-conceptions and assumptions about how Calibre works. This is a viewpoint that experienced users can find it hard to appreciate.

I think that if a user hase not found an answer that they understand in the manual, then it is perfectly correct to start asking questions here. However when such a user finally gets an answer that works and they believe they understand it, what they can at that point do is attempt to write up the problem in such a way that if they had found the problem description in the manual it would have avoided the original question being asked.

The proposed new text for inclusion in the manual can then either be raised in a thread for discussion or submitted for vetting. I believe that Kovid will vet everything that makes it into the manual, so any inaccuracies or misconceptions in the write-up should get picked up at that point.

Sometimes the contribution can be even simpler - just suggestions on how to organise existing material to make it easier to find for the inexperienced user.

Lady Fitzgerald
01-18-2011, 04:31 PM
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.

A problem with writing accurate, detailed documentation when a program is under development is every time one changes or adds code, the documentation changes. Keeping up with both would be a nightmare (even the big commercial programs don't always get it right or, like Microsnot, don't bother with documentation at all). As I said, I would rather see work being done to improve calibre than on the documentation until calibre is pretty much finished (though I probably won't live that long).

Lady Fitzgerald
01-18-2011, 04:35 PM
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.

I chose a) (that was a no brainer for me). Dealing with it involved getting help from the forum and the help I've received here has been excellent.

DuskyRose
01-18-2011, 04:36 PM
Have you contributed documentation for the parts you do understand? ;)

The parts I do understand are already covered under the basics of the web site. I don't have any knowledge past that.

I just figured out how to create separate libraries. I didn't even know it could do that. Someone mentioned it and I saw the discussion by accident.

I *don't really understand all the choices involved* and choosing any particular way to do things over another. Let alone be able to write down for others' what all the choices do.

Archon
01-18-2011, 04:37 PM
The other thing you should do is back up your Calibre library. The frequency of backup would be proportional to how often you add or delete entries.

Before you go making bulk changes to book files back up your library.

This is computer common sense 101 but very few people actually practice it.

That is why Apple came up with Time Machine to make frequent backups transparent.

Get an extra hard drive, get some backup software, and USE it.

Remember keystrokes have consequences.

Happy Tuesday
Archon

DuskyRose
01-18-2011, 04:43 PM
The other thing you should do is back up your Calibre library. The frequency of backup would be proportional to how often you add or delete entries.

Nightly. On an external drive I can grab and run out of the house with.

Then once a month a DVD burn is done and stored in my media safe.

Learned to do that the hard way.

Lady Fitzgerald
01-18-2011, 04:44 PM
Uh...we seemed to have strayed here a bit. The OP was complaining about the website itself being difficult to navigate and lacking prolific screenshots, etc. other sites may have. That I agreed with. I dealt with it by exploring through the website and asking for help here but many people are less willing to do so.

There is also the possibility that the OP was trying to access calibre from another site. Check here (http://download.cnet.com/Calibre/3000-2125_4-10910277.html?tag=mncol;2) for an example.

Lady Fitzgerald
01-18-2011, 04:52 PM
The other thing you should do is back up your Calibre library. The frequency of backup would be proportional to how often you add or delete entries.

Before you go making bulk changes to book files back up your library.

This is computer common sense 101 but very few people actually practice it.

That is why Apple came up with Time Machine to make frequent backups transparent.

Get an extra hard drive, get some backup software, and USE it.

Remember keystrokes have consequences.

Happy Tuesday
Archon

Excellent advice. I use Carbonite for my offsite backup. It does almost immediate backup whenever a file is changed or add, holds deleted files for about a week before deleting, including versioning of current files, and does all that without me having to even think about it (the one exception being the program installation files I hang onto in case I have to reinstall a program; I have to tell Carbonite to do that since they are not considered data). I keep local backups on an external harddrive but I'm lax about keeping it up to date because of the hassle of digging it out, plugging everything in, etc.

gweminence
01-18-2011, 04:59 PM
Recognizing that the thread has slightly gone off track, I have to say that I agree wholeheartedly with Chaley. Companies that develop software nearly NEVER have the same people writing the code, and writing the documentation, In this case, open-source software, where it's just a few small developers...well. Your expectations for thorough and complete documentation should be kept under control. These guys simply do not have the resources to do it like most of us are used to seeing from commercial software.

But, that's sort of moot. Because I've had 3 issues since I've started using calibre. None of them critical. And all 3 times that I posted, chaley and griker immediately answered, helped, and even wrote out a bit of code. Call it 'interactive' documentation if you will, but I'll take that over a pdf file any day.

I think what bothers these guys most probably is the implied sense of entitlement. There IS no entitlement here, only the authors' good will.

Starson17
01-18-2011, 05:13 PM
These guys simply do not have the resources to do it like most of us are used to seeing from commercial software.

Aside from the advantage of more resources, commercial software tends to have long development periods with infrequent releases. It's a lot easier to keep documentation in synch when the software being documented is unchanging. Personally, I prefer Calibre's model where slightly incomplete documentation is balanced by rapid improvement and near instant live support.

Manichean
01-18-2011, 05:18 PM
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.
Speaking as a guy who actually has written a small part of the manual, I'll have to say that I never quite saw the point until now. The documentation, as is, gives a good first introduction, I think, and for everything else there's this forum. I am, however, interested in at least starting an effort to improve the documentation of the areas I know to the point where most options would be explained, without necessarily rewriting/replacing the existing parts. However, right now I have some more important Real Life stuff going on, which should be done *knocks on wood* in about, say two to three months. If nothing has happened till then I'll have a look at the current state of the documentation and see if I'll do something about it.

kovidgoyal
01-18-2011, 05:20 PM
Personally, I prefer Calibre's model where slightly incomplete documentation is balanced by rapid improvement and near instant live support.

:thumbsup: That is, IMO, the coolest thing about calibre.

kovidgoyal
01-18-2011, 05:22 PM
I'll just say this, calibre is a community effort, if you feel some part of calibre is not as good as it should be, roll up your sleeves, and contribute.

I am always happy to accept the contributions of calibre's community, be they in the form of code, recipes, documentation, translations, *useful* bug reports.

phenomshel
01-18-2011, 05:30 PM
Recognizing that the thread has slightly gone off track, I have to say that I agree wholeheartedly with Chaley. Companies that develop software nearly NEVER have the same people writing the code, and writing the documentation, In this case, open-source software, where it's just a few small developers...well. Your expectations for thorough and complete documentation should be kept under control. These guys simply do not have the resources to do it like most of us are used to seeing from commercial software.

But, that's sort of moot. Because I've had 3 issues since I've started using calibre. None of them critical. And all 3 times that I posted, chaley and griker immediately answered, helped, and even wrote out a bit of code. Call it 'interactive' documentation if you will, but I'll take that over a pdf file any day.

I think what bothers these guys most probably is the implied sense of entitlement. There IS no entitlement here, only the authors' good will.

Precisely. Well said!

Aside from the advantage of more resources, commercial software tends to have long development periods with infrequent releases. It's a lot easier to keep documentation in synch when the software being documented is unchanging. Personally, I prefer Calibre's model where slightly incomplete documentation is balanced by rapid improvement and near instant live support.

Again, well said!

:thumbsup: That is, IMO, the coolest thing about calibre.

Yes, it is :D

I'll just say this, calibre is a community effort, if you feel some part of calibre is not as good as it should be, roll up your sleeves, and contribute.

I am always happy to accept the contributions of calibre's community, be they in the form of code, recipes, documentation, translations, *useful* bug reports.

Kovid has been very supportive of the community's wants and wishes, even if he doesn't see the need for whatever it is that is wanted/wished for. If I had the knowledge and a unique perspective, believe me, I'd be in there up to my elbows. As it is, however, my programming is non existent, and about the best thing I can offer is proofreading, LOL. If you want that, let me know. ;)

Lady Fitzgerald
01-18-2011, 06:39 PM
:thumbsup: That is, IMO, the coolest thing about calibre.
:ditto:

I'll just say this, calibre is a community effort, if you feel some part of calibre is not as good as it should be, roll up your sleeves, and contribute...

Sadly, not all of us are qualified to. The last programming I did was very basic Basic 8.0 (back before you were a gleam in your Daddy's eye).

Dopedangel
01-18-2011, 10:29 PM
I always thought if someone collected all the questions asked in the forum and their answers. And then set them up by each device they are for we could get a very comprehensive manual not technically correct but still.

May be some of us regular forum users if we are willing to divide the work by Topics/(Devices)
I am willing to collect the questions and answers that I can find about all Hanlin v3 clones that come up as thats the device I use plus maybe directory structure as thats what my device uses (no wait I don't want to take the folder structure headache:smack:)

DoctorOhh
01-18-2011, 11:26 PM
Personally for a open source project of this magnitude, complexity and state of flux I have always been impressed with the amount of documentation that does exist. As others have pointed out it isn't always as complete or as plainly stated as some would hope, but none the less I am constantly amazed at the consistent on-going updating of the documentation that accompanies all of the feature updates.

CWatkinsNash
01-19-2011, 12:33 AM
I always thought if someone collected all the questions asked in the forum and their answers. And then set them up by each device they are for we could get a very comprehensive manual not technically correct but still.

May be some of us regular forum users if we are willing to divide the work by Topics/(Devices)
I am willing to collect the questions and answers that I can find about all Hanlin v3 clones that come up as thats the device I use plus maybe directory structure as thats what my device uses (no wait I don't want to take the folder structure headache:smack:)

I'd be willing to help work on collecting the Kindle-related questions and building on that. I've got a lot going on work-wise right now but I can find some time here and there and focus more on it when things slow down for me.

unboggling
01-19-2011, 04:16 AM
I'm willing to help with documentation. Yesterday when I mentioned that python scared me, GRiker recommended Mark Lutz's book. I noticed there were 3 and bought them all:
Learning Python, Programming Python, Python Pocket Reference. Regarding documentation of calibre, I think it would be useful to think of documentation as having several levels and separating them:

1. Beginner's Guide to calibre. Overview, not technical. The conceptual framework. So technical revisions would rarely need to be included/updated. Authors/contibutors, a group of anyone willing who is past beginner stage.

2. Power Users Guide to calibre, or Programming calibre. Authors/contributors, any willing power users, vetted but not written by developers.

3. Developer's Documentation. Whatever they think it should be since it's primarily for them, with perhaps a few power users looking at it once in awhile.

Manichean
01-19-2011, 04:38 AM
I always thought if someone collected all the questions asked in the forum and their answers. And then set them up by each device they are for we could get a very comprehensive manual not technically correct but still.

May be some of us regular forum users if we are willing to divide the work by Topics/(Devices)
I am willing to collect the questions and answers that I can find about all Hanlin v3 clones that come up as thats the device I use plus maybe directory structure as thats what my device uses (no wait I don't want to take the folder structure headache:smack:)
I wouldn't necessarily start with the forum and pick out single topics from there. The relevant topics are so fragmented across many, many threads, I fear that it might take more time collecting them than writing them from scratch.

1. Beginner's Guide to calibre. Overview, not technical. The conceptual framework. So technical revisions would rarely need to be included/updated. Authors/contibutors, a group of anyone willing who is past beginner stage.
This, in my opinion, is already nicely covered by the documentation as it is today.

2. Power Users Guide to calibre, or Programming calibre. Authors/contributors, any willing power users, vetted but not written by developers.
This is the part that, perhaps, ought to be created. Although I see no need fo the developers to necessarily be involved, if they don't want to.

3. Developer's Documentation. Whatever they think it should be since it's primarily for them, with perhaps a few power users looking at it once in awhile.
This would probably be rather useless. Users on this stage will be able to figure things out on their own, if not, they don't belong here. Also, it would take away precious time from development for little to no benefit. Chaleys post about why he doesn't like writing docs applies here.

unboggling
01-19-2011, 04:47 AM
@Manachean,
1. Yes.
2. Yes.
3. Like i said, whatever developers think it should be. If it doesn't exist, it's their problem.

unboggling
01-19-2011, 04:54 AM
Also, I noticed there are many authors and some editors and publishers hanging out on MobileRead, and some use calibre. A call for help with documentation addressed to the entire MR forum, or at least a post in General Discussion, might result in some skilled writing & editing volunteers.

Manichean
01-19-2011, 05:06 AM
Also, I noticed there are many authors and some editors and publishers hanging out on MobileRead, and some use calibre. A call for help with documentation addressed to the entire MR forum, or at least a post in General Discussion, might result in some skilled writing & editing volunteers.
I'll just say that writing and technical writing are two very different pairs of shoes.

Lady Fitzgerald
01-19-2011, 05:16 AM
While I feel that calibre's documentation is lacking, I also feel that trying to write complete, detailed documentation at this time would be a waste of time since calibre is constantly and rapidly evolving, it would render much of the documentation outdated in short order. I feel more complete documentation should wait until calibre is in a more complete form.

I feel the same way about calibre's GUI; it's rather stark, lacking color, unfriendly to non-geeks (like me), etc. and the various screens are sometimes inconsistent in how things are done but trying to clean things up and add pizzaz (without bloat) at this time would be a waste since calibre is still evolving (and will be for some time to come). I've been using calibre less than a year and it has changed (almost all for the better) dramatically.

Lady Fitzgerald
01-19-2011, 05:17 AM
I'll just say that writing and technical writing are two very different pairs of shoes.

:ditto:

Manichean
01-19-2011, 05:36 AM
I feel the same way about calibre's GUI; it's rather stark, lacking color, unfriendly to non-geeks (like me), etc. and the various screens are sometimes inconsistent in how things are done but trying to clean things up and add pizzaz (without bloat) at this time would be a waste since calibre is still evolving (and will be for some time to come). I've been using calibre less than a year and it has changed (almost all for the better) dramatically.
Huh. I like the GUI. It's simple, well laid out and easy to use. And, above all, customizable. But then, I am a geek, so my opinion may not matter much for that, since I'd probably been happy with command line only ;)