The Future of this Forum

[Lady Fitzgerald]

Originally Posted by GRiker

@LadyFitzgerald:

You should be able to learn everything you to know about creating catalogs from the first post in that thread. After we reorganize things, the first post will be the read-only sticky.

If you would go to that post and point out what is unclear, I will try to rewrite it in a simpler fashion. If you choose to do follow up, please do so in that thread rather than this one. I am genuinely interested in making my how-to instructions accessible to users of all skill levels.

G

Again, another perfect example of what I've been saying. You feel I should be able to understand what's in the thread. However, the fact is I do not. This was just an example of the point I was trying to make so I won't pursue it here. I have bigger fish to broil right now so I'm not interested in dealing with it right now.

[kiwidude]

I'm happy to help out in the plugins subforum, but would do that regardless of whether I am an admin for it or not. My "expertise" is limited to the gui plugins mostly. It would be great as you have suggested to have each with their own thread and a sticky with indexes. As I'm in the process of updating/merging a few of them it would be nice to lose some of the "historical" posts that are no longer relevant.

[Manichean]

Originally Posted by garcle

How about shutting down the main user manual and moving it to the wiki?

That way you would only have one place to send people.

And you would have the Wiki advantage of being able to let the community evolve the documentation in a hierarchical and hyperlinked structure. The can quickly be added to as new "solutions" to common problems are written.

We actually have that advantage already. You can send Kovid additions to the manual and he'll include them. The downside here is that everything goes through him, but as long as he doesn't complain about it, I vote we keep the system.

Originally Posted by honeyrose

The Quick Start guide on the Calibre version I downloaded simply does not open - not on Windows XP Pro on my machine at least. I just get an unknown file format error message, regardless of whether I click on the image or the title etc. But still people here tell me to read the User Guide. You know I would if I could.

Well, as one of the persons who answered your thread, let me sketch my initial impressions: You said you had installed it, and, after doing what sounded to me like aimless clicking, got an explorer window with the folder of a book opened, which you then couldn't open. (That is no surprise, by the way, if you haven't registered an application for ePub.) There wasn't much more detail available. So I assumed you hadn't bothered to read any documentation and thus had, somehow, misunderstood how Calibre is supposed to work. So, instead of rewriting the introductory guides available, I chose to link to those available online.
I would have reacted entirely different, by the way, if I had, for example, known what you mentioned in this thread: That the dropdown menus are giving you errors (I just gave this thread a quick once-over, but I seem to remember you saying that).

[garcle]

Originally Posted by Lady Fitzgerald

Ok, here is a perfect example of why documentation needs to be simplified for many users. I know more about computers than most of my friends yet the above passage made absolutely NO sense to me whatever. And, to be honest, I don't care what it means. I'm not a programmer and don't want to be...

I think you hit the nail right on the head. Regular Expressions are a tool for programmers. In fact a "regular expression" (regex) is a kind of "shorthand" for finding and (optionally) changing a letter or number sequence, which has any kind of pattern. Those of us old enough to remember short-hand as a method to record dictation, can think of regular expressions as "shorthand programs". A person without some computer programming knowledge should not feel bad if they cannot understand regular expressions, these are non-trivial and very powerful program structures.

A point that comes to mind though is this, how many regular expression are needed for Calibre? I have a programming background so can hack a regex together for my needs, but there is probably a set of regex classes that cover 90% of Calibre user requirements. Classifying the regexs used and listing them in a sticky would be one thing. But looking deeper at the root cause behind the need for the regex is the next step. Wherein the "capability" behind the requirement is implemented as a button or menu item within the program itself.

[garcle]

Originally Posted by Manichean

We actually have that advantage already. You can send Kovid additions to the manual and he'll include them. The downside here is that everything goes through him, but as long as he doesn't complain about it, I vote we keep the system.

No we don't You cannot possible compare a wiki which is edited in situ, with the current process of updating the manual which requires the rst files to be checked out, edited without breaking the rst format, checked in , updated, rinse and repeat. For a contributor to get involved this is cumbersome and unnecessarily complicated and which, I'm guessing, leads in part to the fact that the manuals are *not* kept up to date.
Said by the person that made the last major edit to the GUI section of the manual.

[nynaevelan]

Hi All:

I see this thread has gone off to a tangent that is best viewed by the power-users. While I know I will never be a power-user I like to think of myself as semi-advanced, but no matter how much I research and read up on regex, it just goes over my head. This is not the first program I've come across that uses it but like there, I just do not get it. I know you all dedicate alot of time and effort not only in the documentation but in helping users such as myself here. If at all possible when updating the documentation and forum you could include some examples that is great, I am pretty good at following along with those. I have the utmost respect for what it is you all do. I have received a tremendous amount of help both directly and indirectly through the assistance you have offered here on the forums.

And as a side note for the poster who stated us noobie's and non power users do not use the faq and documentation, I went back and re-read them while they both give some good basic understanding of Calibre and some very technical information, they really do not explain alot of the functionality of Calibre, so I am looking forward to your continued efforts in the upcoming changes, although I know where you all will enlighten me in some areas it will open up many more areas where I get to show my ignorance.

[kovidgoyal]

Guys, can I suggest we move off regexps please, and focus on how to improve this forum.

I get that some of you will never understand regexps, that's fine. Think of them as a programmer's feature. I never intended calibre to have only features usable by everybody. Remember that I (and most calibre contributors) write calibre to make it useful for ourselves, not just for others. Regexps are an awesome tool for someone with the knowledge to use them.

The vast majority of features in calibre are simple to use, intuitive and cover most of what the average user wants to do with their book collections.

The idea of this thread is to find the best way to structure this forum so that those of us that respond to questions are not overwhelmed.

[Manichean]

Begin Edit: Sorry, Kovid, I read your post after answering. However, I believe this can stand as a final note on regexes in this thread
End Edit

Without answering every one post about regexes individually, I'd like to at least make two points about those darn things:
First, you need to understand that computers (generally) lack the semantic understanding of text that we humans have. A computers sees an ebook not as a collection of words gathered into sentences that convey meaning, but as a string of characters- a string. Thus, you need to understand that regular expressions also only operate on strings- there is no way you can get the computer to understand what you're trying to do on the level of words or meanings, you have to tell it exactly what to do on the level of essentially manipulating single characters. This is, in particular, aimed at Elfwreck (and not intended as a criticism, only as something I got the feeling you didn't quite realize).
That said, my second point is this: To all those here complaining about regular expressions, I'd like to ask you to read the tutorial that's available in the manual. (Better yet, read the first post of the original thread, since that is likely to become a sticky if the changes proposed here are implemented- although I haven't gotten around to update that to include the changes made in 0.7.42.) The goal of that tutorial is to take the user from the point of knowing nothing about regexes, but being willing to learn, to the point where he (or she) is comfortable enough to use them in Calibre. Bearing that in mind, please tell me what should be improved about it- preferrably relatively precise, as I don't know how to process the information that "it is just too difficult" or something. If I know what to improve, I'll try to do that, although it may take some time. (To avoid derailing this thread, I'd suggest you PM me.)

[user_none]

Originally Posted by Lady Fitzgerald

I use MS Word heavily. I had no trouble learning to use it, including some of the more complicated aspects...

Same goes for when I first got Adobe Acrobat Standard a little over a year ago.

A better example to compare to would be Excel instead of WYSIWYG tools. Excel has a very complex formula language and even includes and entire Visual Basic scripting engine.

Originally Posted by garcle

A point that comes to mind though is this, how many regular expression are needed for Calibre? I have a programming background so can hack a regex together for my needs, but there is probably a set of regex classes that cover 90% of Calibre user requirements.

Nope. Having dealt with the header and footer regex stuff there isn't even anything close to one regex to rule them all. As far as content goes ebooks are formatted so differently that even books by the same author and in the same series often need different regexes.

Same goes to extracting metadata from file names that there so many different ways people have their books names there is no one regex that works most of the time. Each variance needs a different regex. While it might be nice to include defaults that work against a number of cases, I don't think throwing 20 different regexes at a user and saying pick one would help much. Especially when there is a good change none of them will work.

[Vandy]

Originally Posted by kovidgoyal

@Vandy: If you are offering to help with documentation, that's great. Just dive in, look at the current User Manual and feel free to contribute to any section you think needs to be improved/updated. Just send the updates/additions to me, and I'll merge them into the User Manual.

Doing that is also an excellent way to learn about calibre.

Hello, Kovid.

Thank you for your reply. I shall dive into the existing documentation, check around the forums, ask the necessary questions and work on an update to the documentation. Do I PM you, post my updates in a thread for comment or...?

Again, thanks.

Regards,

Vandy

[Elfwreck]

Originally Posted by Worldwalker

It's not like learning terminology is hard. Humans are set up for that sort of thing. Do you know the parts of a book? There's a cover, sometimes with a dust jacket, there are pages which may be fixed in signatures, there's a spine, page numbers, perhaps a table of contents and an index, and so on.

And I don't mind learning the vocab. It's just that a lot of geek fields don't have a Geeklang-to-English glossary; they have a dictionary written in Geeklang that describes terms in relation to each other. I can tell when I've reached a scientific topic on Wikipedia, because the opening paragraph is incomprehensible. (See light. Or worse, wavelength. Twitch. Good thing I already know what those are, because I'd never be able to figure it out from those explanations.)

When I need to, I study the terminology enough to figure it out. It's easier if it's in a field I have a connection to or direct interest in, but it's not impossible to start from scratch. (However. There's a reason so many authors provide a glossary in the backs of complex world-building books.)

That's what I find so ridiculous about people trying to claim that a specialty's precise terminology (and it's almost always computer-related) serves as some kind of shibboleth to keep out the uninitiated. Terminology is the easy stuff.

No, it's just the first hurdle. Which, if it's high enough, can make the field not worth entering. And I can understand not providing it; those terms are used because they're effective; rephrasing them in non-technical terms means basically describing them wrongly.

I've written a basic Pagan-to-English vocab guide; it was weird realizing how much it felt like dumbing down or glossing over the important parts. And how much I left out, because "basic" kept trying to explode. 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, and they could find that info on their own.

And a Calibre glossary could have the same intent--just enough vocab to be able to ask for help coherently, and to allow for easy absorption of other new terms.

So, back to the topic at hand, what we need isn't to translate technical terms into "computer TV set"-speak for users; we need to provide adequate explanations of those technical terms so they can understand what other documentation means, and use the terms themselves. That gets everyone on the same page. Perhaps a glossary section of some kind could address this.

I'd like that; I don't think we need a complete "Calibre for Dummies" book, but a page or two of vocab for people who don't come out of a programming background would be helpful.

[waller4343]

Fun Thread. Almost as fun as the ones about changing the file structure of Calibre. I would like to say that, free or paid, Calibre is the most frustrating software I have ever used. It is improved almost every week, it gets features that I didn’t even know I needed added. Don’t get me started on the catalog and how it helps me keep track of my books while actually using it on the Kindle. Or custom columns that I can create to make my library easier to manage. Oh, and the composite fields that let me sort my books on the Kindle in series order. Sheesh, enough already.

I can’t count the number of times that I “wished” that Calibre would do something that would make it more useful to me and it pops up in the next release. I don’t even have to go to the bother of asking for it. My weekends are shot cuz most Fridays there is a new release and I have to try out the new features. I get ideas from the “power users” in the forums that MAKE me redo all my work to utilize Calibre in a more efficient way.

Seriously though, thanks to all the guys and gals, power users and newbies with their answers and questions, young and old that have made this such a great program. I can’t use all the features available, but what I can and do use - Great! Like the different Office Suites out there - I use them more productively than most, but I will never be able to everything they offer.

As for revamping the forum, I’m in the minority. I guess I enjoy the silly questions that I don’t have to answer. But I understand the frustration that the gurus must feel answering the same cycle of questions over and over again, and doing it voluntarily. I don’t usually come to the Calibre forum looking for answers, I usually just look at the first couple of pages of threads looking for ideas about how to use Calibre. And its present format is great for non-structured types like me. But I could probably survive if you had at least one random type topic for me to browse.

[Worldwalker]

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.

[kovidgoyal]

@Vandy: Feel free to PM me with your changes. If you would like public feedback on something you plan to do, then start a thread.

[ldolse]

I'm happy to help out with the docs/subforums, conversion is probably where i can provide the most value. That said, I've read through the thread, and I do have a few comments that haven't really been covered.

Calibre's seen a LOT of new users in the last couple months. The newbies that actually sign up for this forum to ask questions are a tiny fraction of those new users. I've recommended Calibre to several friends over the last couple months myself, and the only comment I get back from them is that Calibre is the greatest thing since sliced bread - no tech support requests at all. I haven't told them about this forum as a support resource and none of them have signed up to ask for help. Anyway my point is the extra requests for help are just a part of Calibre's increasing popularity, probably not anything to get too excited/worried about. There are a lot of happy users out there who will never create a mobileread or bugtracker account.

I don't know how we get new users to upgrade, but one of the other issues I see is that most new users have no idea how fast Calibre moves - I don't think there are many/any other software projects that improve as rapidly as Calibre. A lot of questions/problems recently are from users using old versions of Calibre and don't bother informing the people trying to provide help here of that fact. Probably one of the things that needs to be front and center in the forums is that you really should check your version number and upgrade before asking for help.

One thing I really liked in 7.42 is that Kovid linked the new panels directly to the relevant documentation - this is probably worth doing for many of the different GUI panels, and will probably reduce a lot of the 'how does this thing work' type threads since the relevant docs are a click away and don't require any searching/Internet navigation.

I'd also like to stress that it is very easy for people to contribute to the actual Calibre docs. You do need to get involved to the degree that you need to sync the source code, instructions are here:
http://www.calibre-ebook.com/user_manual/develop.html

Editing the actual docs isn't hard, though how to do that isn't particularly well documented in and of itself. Is this something that needs to be made easier for people who wish to contribute?