Just as an aside, I
am a programmer and regexes still scare me.
Vandy, it's great to see someone with tech writing skill offering to help. By and large, people here are either coders who have other things to do with their time than write documentation (besides, if it was hard to write,
shouldn't it be hard to understand? (that's a joke)) or users who just want to get an answer and get back to what they were doing before calibre did something odd, and don't have the background to write good docs. Calibre is a personal project (Kovid's) that kind of grew some (or gruesome) and the fact that it has any documentation at all is fairly amazing to begin with. Kovid wrote calibre because he needed a program to do certain things, other people have contributed because they needed it to do other things, and the people who answer questions do it, not to provide world-class customer service, but because we like solving problems (which is also why the hundredth person to not bother to read the manual will get short shrift). Writing docs that work is as important as writing recipes that work, and one that a lot fewer people here are good at.
Elfwreck, I think you hit it on the head with your description of the Pagan-to-English vocab guide: "I eventually decided that, anyone who wanted more than basic knowledge would have enough vocab not to get themselves shouted out of the places where more advanced details are available...." That's
exactly what people need: a vocabulary bootstrap. A good glossary could work wonders there.
Of course, there are people who
still won't bother, and want everything rewritten for their particular level. I have to wonder if they go into a Pagan ceremony and say "well, it's okay, but could you make it more like Lutheran?" They're the ones I personally don't give two hoots about, because they're not trying. They're showing no respect for the people they're dealing with, and expecting to be catered to. A little respect -- which can be as simple as
not starting out by insulting Kovid, which a disturbing number of people have missed out on -- goes a long way. It's fair to say that everyone in this thread understands and demonstrates that, but a look around some old threads will provide some unpleasant contrary examples. Calibre
is, when all is said and done, a hacker project, and people are expected, as part of the culture surrounding it, to take care of themselves; those who don't are the "welfare queens" of calibre, and responded to accordingly.