Something is way off

[phenomshel]

Originally Posted by gweminence

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!

Originally Posted by Starson17

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!

Originally Posted by kovidgoyal

That is, IMO, the coolest thing about calibre.

Yes, it is

Originally Posted by kovidgoyal

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]

Originally Posted by kovidgoyal

That is, IMO, the coolest thing about calibre.

Originally Posted by kovidgoyal

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]

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)

[DoctorOhh]

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]

Originally Posted by Dopedangel

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)

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]

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]

Originally Posted by Dopedangel

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)

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.

Originally Posted by unboggling

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]

@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]

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]

Originally Posted by unboggling

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]

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]

Originally Posted by Manichean

I'll just say that writing and technical writing are two very different pairs of shoes.

[Manichean]

Originally Posted by Lady Fitzgerald

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