Something is way off

[DuskyRose]

Originally Posted by silasgreenback

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]

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]

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]

Originally Posted by 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.

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]

Originally Posted by DiapDealer

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]

Originally Posted by DiapDealer

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]

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]

Originally Posted by Archon

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]

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 for an example.

[Lady Fitzgerald]

Originally Posted by Archon

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]

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]

Originally Posted by gweminence

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]

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.

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]

Originally Posted by Starson17

Personally, I prefer Calibre's model where slightly incomplete documentation is balanced by rapid improvement and near instant live support.

That is, IMO, the coolest thing about calibre.

[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.