The Future of this Forum

[GRiker]

Originally Posted by kovidgoyal

I've added a tentative new forum structure to the first post of this thread, please propose modifications as you see fit.

A subforum for Interface Action Plugins.

G

[kovidgoyal]

Originally Posted by GRiker

A subforum for Interface Action Plugins.

G

Done .

[Piper_]

One thing that usually works well for questions that are answered in a guide/wiki/faq is to give a link directly to the section that answers it.

Users do tend to be very impatient and easily intimidated, so the smaller and more specific the section, the more likely people will read and use it.

They don't usually care about whys and wherefores (even though it's important to include in the documentation for those of us who do). They just want to know "how do I" for their specific need and to be given a 1.2.3. step-by-step answer.

Knowing what specific answer applies to their specific need is usually the hard part, and so there will always be repeat questions, but at least showing them a link to the answer is easier than typing out a full answer and explanation.



I need to go for a bit, but the other thing I'd suggest is labeling (even color-coding) things in terms of difficulty (basic/moderate/advanced), and letting it be known to users that more study effort is expected from them if they want to do things that require advanced understanding or experience.

A lot of us love to see calibre grow as a power tool, but the price of that is the effort it takes to keep non-power-users from being confused and power-users from being frustrated or overwhelmed with hand-holding them.

[Starson17]

Proposed forum Structure:

All stickies are read only

Sub forums:
Recipes: 
  Stickies:
    1. Code snippets
    2. Howto use a custom recipe in calibre

In the Recipe Subforum: The code snippets sticky thread in recipes probably should be open or it will stagnate. There have only been two inadvertent posts in that thread. I'd move it to second after HowTo, (which will help avoid inadvertent posts in an open sticky - because some new users try to post in the first sticky) and I'd name the Howto:

"Howto write and use custom recipes."

HowTo would be a good place to add links to the various recipe source materials, like Recipe Tips, the Calibre API, the BeautifulSoup and Mechanize docs, etc.

[kovidgoyal]

I don't think the order of the stickies is controllable. Other two suggestions implemented.

[Elfwreck]

Originally Posted by user_none

As for the idea of having to know regexes, too bad. The features that use them require them. There is no way around it. If you don't know how to write a regex for that feature then don't use it. Sorry but many of the features like search and replace cannot be acomplished in any other way that would be simplier and cover as many use cases.

Which is why I barely use Calibre, and mostly for conversions to something I can open in Word and reformat to reader-sized PDFs. I don't know regex, and the tutorials assume a level and type of geekery I don't have.

I love Calibre and encourage lots of people to use it; I barely touch it myself because the learning curve is steep enough to be frustrating, and my doc conversion skills in other programs make it not worth the effort.

Originally Posted by chaley

The first two lines from the wikipedia article on regular expressions (emphasis mine)
Regular expression
In computing, a regular expression, also referred to as regex or regexp, provides a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. A regular expression is written in a formal language that can be interpreted by a regular expression processor, a program that either serves as a parser generator or examines text and identifies parts that match the provided specification.

My eyes glazed over at "strings of text."

I'm vaguely aware that "regex" is High Geek for "search function," and is more powerful & versatile than just calling it search-and-replace. That doesn't make the explanation make any more sense to me. I can follow it if I concentrate very hard, and translate about half the words individually, but that's not the same as "read and understand."

Text, for me, is made of words. Or letters. Not "strings." When I think about it, I realize why the term "strings" is used; "words" and "characters" aren't specific and accurate enough. But that doesn't change the fact that an explanation of a geek term written in other geek terms is still opaque. I get that simplifying the explanation, or using layman's terms for the details, would be inaccurate; that doesn't make it any easier to understand.

There is probably no simple solution for this, just a need for patience all around.

Someone (who is fluent in the Calibre subdialect of Geek, and has ridiculous amounts of spare time & goodwill toward their fellow ebook readers) might consider putting together a small collection of tutorials in common newbie topics, like "How To Make Collections" or " or "How To Make Chapter Headings," that being the hurdle that's caused me to mostly give up on it. (I got instructions. I attempted to follow them. The results did not have chapter headings, or did not have page breaks before chapter breaks, and I shrugged and went back to making custom-sized PDFs with bookmarks.)

[phenomshel]

Originally Posted by Worldwalker

cybmole, chill. We're supposed to be on the same side here.

Despite his Praky-like respons, cybmole does have a point. To us, conventional shorthand means the same thing as standard terminology; to someone who's not familiar with it, it doesn't. There really are people who don't know that a "regex" and a "regular expression" are the same thing. I'm married to one, and I'm not married to an idiot; just to someone who doesn't geek in the quite same directions as I do. We don't need to dumb down material, we need to smarten up users -- but we need to give those users somewhere to grab hold. This should include both using some standard of terminology in documentation, and providing a glossary where they can find out what it means if they don't already know. "Regex" is a low-content term for a complicated concept; at least "regular expression" is made of words that make some kind of sense, so the reader can hold onto some hope that they can eventually learn what those words mean in this context and how they go together. Calling them "fluffy unicorns" would be wrong because that's not a standard term for the concept; "regular expressions" is both standard and meaningful.

Originally Posted by Elfwreck

Which is why I barely use Calibre, and mostly for conversions to something I can open in Word and reformat to reader-sized PDFs. I don't know regex, and the tutorials assume a level and type of geekery I don't have.

I love Calibre and encourage lots of people to use it; I barely touch it myself because the learning curve is steep enough to be frustrating, and my doc conversion skills in other programs make it not worth the effort.


My eyes glazed over at "strings of text."

I'm vaguely aware that "regex" is High Geek for "search function," and is more powerful & versatile than just calling it search-and-replace. That doesn't make the explanation make any more sense to me. I can follow it if I concentrate very hard, and translate about half the words individually, but that's not the same as "read and understand."

Text, for me, is made of words. Or letters. Not "strings." When I think about it, I realize why the term "strings" is used; "words" and "characters" aren't specific and accurate enough. But that doesn't change the fact that an explanation of a geek term written in other geek terms is still opaque. I get that simplifying the explanation, or using layman's terms for the details, would be inaccurate; that doesn't make it any easier to understand.

There is probably no simple solution for this, just a need for patience all around.

Someone (who is fluent in the Calibre subdialect of Geek, and has ridiculous amounts of spare time & goodwill toward their fellow ebook readers) might consider putting together a small collection of tutorials in common newbie topics, like "How To Make Collections" or " or "How To Make Chapter Headings," that being the hurdle that's caused me to mostly give up on it. (I got instructions. I attempted to follow them. The results did not have chapter headings, or did not have page breaks before chapter breaks, and I shrugged and went back to making custom-sized PDFs with bookmarks.)

I love Calibre,(and use it daily, but realize I have barely scratched the surface of what it is capable of), and highly respect Kovid and the rest of the developers, as anyone who reads my posts here should be able to tell. (At least if they ignore the smart remarks peppered in there, LOL!) However, I do have to agree with the posts I quoted above: Regex might as well be Greek to me (and I don't speak Greek). Not wanting to be a troll, or labeled clueless (which I am when it comes to Regex), I did what research I could on my own before my own eyes started glazing over (which was about the same time as Elfwreck's), and then said, "never mind, I'll live without them". Which I have, quite happily, so far. The same with the GUI plugins. I saw "GUI" and my mind went, "Oh, yayyy! Something I can follow..." and .. ummm, no. Which of course is not anyone's fault but my own. I would LOVE to be able to help with calibre, but my one area of expertise is proofreading, and there doesn't seem to be much call for that, LOL. I love GUI improvements, as Kovid can testify to (read the thread about wanting a cover/grid/bookshelf screen), but as to how to implement that, I don't have a clue. I even tried downloading source and learning Qt Designer, only to find out that the main calibre interface uses pure Python, not a design interface I can "see". At that point, I decided I'd just sit back and wait patiently (or as patiently as possible) until someone had the time and the desire to mess with it.

Yes, I'm rambling (Worldwalker, you're contagious?), but I think you've hit the nail on the head. Give me something to grab, and I'm more than willing to take it from there, I just need that starting point.

Disclaimer: NONE of the above should be taken as a complaint, mainly because none of it is intended to be a complaint, or a reproach, or anything else negative. If anyone is at fault for my lack of understanding and eyes-glazing-over, it's myself.

[theducks]

Originally Posted by kovidgoyal

In order to do that, the Wiki would first have to achieve feature parity with the current User Manual.

Isn't there a need to maintain (leave in place) users manuals for older versions that some users are locked into because of their reader or computer (O/S)?

Calibre 6.xx last for Sony...
Calibre x.x Last for MAC OSX n.n

Each time you hit one of these 'limits' a snapshot of the UG gets locked
(Could the Help button send the O/S and Calibre version as part of the help request? Dynamic help )

[Worldwalker]

Originally Posted by Elfwreck

Text, for me, is made of words. Or letters. Not "strings." When I think about it, I realize why the term "strings" is used; "words" and "characters" aren't specific and accurate enough. But that doesn't change the fact that an explanation of a geek term written in other geek terms is still opaque. I get that simplifying the explanation, or using layman's terms for the details, would be inaccurate; that doesn't make it any easier to understand.

The big problem isn't so much understanding as it is specificity. People who are writing documentation generally want to do it right, and right means both accurate and precise. (by the way, this is general, not Elfwreck-specific) What I find bizarre is the way some people limit their refusal to learn terms to computer technology only. For example, I knew someone who refused to use the terms "monitor" and "keyboard" and insisted on saying "computer TV set" and "typewriter" and would pretend not to understand if someone else didn't use that terminology -- yet this same person memorized the Latin names of innumerable plants (he wasn't a botanist; this was a hobby) and used them in preference to their common names, and insisted that other people should learn them too because they were more accurate (which is true, but not much use to someone who only knows that white thing as a daisy). Any time we learn to use a new technology, we learn the terms that go with it. We learn that we cook in frying pans, not flat-hot-things, and our cars have gearshifts and brakes, and our sewing machines have presser feet, and the birds outside my window are eating suet out of a suet basket. But somehow, people seem to think that this is unnecessary for computers and software. Just like knowing that a car has an accelerator and a brake, not a go-pedal and a stop-pedal, we need to learn what the computer things we're dealing with are called.

Going back to what Elfwreck said about text being made of words: Is the phone number (123)-456-7890 text? How about the postal code K1A 0H8? Or the ISBN 0307454541?I wouldn't call those words, since they're not something I could pronounce, but they are text. They're strings. They're strings that do not include words. From the point of view of someone working with regular expressions, it's just as likely (if not more so) that you might need to apply the regex to a phone number or, in the case of calibre, an ISBN, than just ordinary words. So they say "string" instead of "words" because that covers everything. If someone talked about regexes being useful for dealing with words, there would be the question "Is there something like a regex I can use to look up this ISBN, then?"

Unless we want to go around calling a monitor a "computer TV set" (and probably a different term for every person), we have to agree on some pre-defined set of terms. That's what we've done with cars and cows, pans and plows, all throughout history. Computers and software are no different.

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. How about your house? You know it has stairs and windows, and the windows are made up of panes fixed in sashes, possibly divided by mullions, and they're made of glass, maybe double-glazed. That bird I'm looking at has a beak, feathers, feet, a crest, a gray back and pale breast, and I could go into much more detail to a fellow birdwatcher. There's nothing more arcane about what "regex" means than what "wingbar" means, and it's something you need to know if you're going to be dealing with that category of things.

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. If I just had to talk the talk, I could pass myself off as a professional athlete or an airframe and powerplant mechanic, given a little time to study up on the proper words. I couldn't actually play a good game of rugby or fix your airplane, but if I just had to understand what people were saying and sound like I knew what I was talking about, that would be easy.

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.

[Vandy]

Hello, All.

Settle back with your cuppa joe and relax. This is going to be a long one...

I've taken the time to read through this thread a couple of times and must say that the level of knowledge seems to be on par with the level of disgust towards **noobie** users. (Using the unflattering noobie term was done on purpose.)

I am a VERY GREEN user of Calibre but found it quite simple to get it to do what I want it to do -- convert other book formats to .mobi. I found it very simple to figure out and do up to and including using the batch mode and editing data.

Please accept my thanks and appreciation for providing such a wonderful software application for our use.

In my 38 odd years of working within the Data Communications / End User Computing Customer Service World (of some form and fashion), the ONE TRUTH I've learned is that if you are going to provide a service to your customer don't do it half-a**ed. The goal of customer service is to, not surprisingly, provide the customer service. In this respect, service can be defined as answering questions, pointing the customer to an appropriate resource, helping to solve a problem / bug, etc.

Now... Having writing the above, Customer Service does not mean that you should be a doormat for your customer. I can commiserate with every one of you who have related your customer service horror stories -- I've had them as well. HOWEVER, being short or downright spiteful (I believe the term I read was "being a dick...") doesn't do anything to help the customer, the applications or the programmers who wrote and maintain it.

In my career, I have created, staffed and managed three separate helpdesks in three different companies. NOT ONCE did I ever turn a customer away who asked for help. Let me further clarify my statement. I made sure the customer either got the answer to their question or, was given a resource from which they could find it themselves.

There is always going to be a "bad apple" type of customer who doesn't want to do any of the leg work to get an answer and, as I've read throughout this thread, believe they have the right to said answer (entitlement). This is where true customer service can shine.

Someone who is providing world class customer services NEVER stoops to the level of the customer's "state-of-mind". If you do, you've lost the battle before it begins. I am a firm believer in empathizing with your customer BUT... NEVER sympathize. Again, you're dropping yourself to their level and any "business separation" has been compromised when the customer senses that they've drawn you in.

It is NEVER WRONG to politely point the customer to a resource they can use to get their own answers AS WELL AS let them know that THIS is the proper way to get help for their questions. Direct interaction between the customer and customer service person should be reserved for those times when true help is needed -- a problem in the application; a feature whose function and /or purpose can't be found in the documentation; a feature request; etc.

Actually, there isn't any reason why a Feature Request Thread couldn't be created and customers directed to that thread to post their requests.

Let me suggest a few ways in which Calibre Customer Service can become world class:

1) Have documentation that is written for and at the customer's level.
I'm not advocating that there shouldn't be technical terms, jargon, explanations, etc. It should be self-evident in today's technological world that this cannot be avoided nor should it be. However, an explanation should be provided or a resource made available to the customer for them to find their own explanations.

Well written documentation is the foundation for any good application. Having written that, we ALL KNOW that the "lead the horse to water..." analogy will always apply. There are some customers who just won't and /or refuse to ready the documentation. This is not an excuse, however, for not having the documentation.

2) Have resources (either internal or external) made available to the customer.
I like the ideas I've read within this thread concerning sub-forums, use of sticky topics, etc. These are excellent ways to provide the customer with an internal resource source. Likewise, using a Wiki externally is an excellent resource to provide.

3) Treat ALL customers with respect and politeness -- even the difficult ones.
Answering an angry customer in kind isn't going to solve any problems -- rather, it will only serve to exacerbate an already volatile situation. I'm not advocating that all customer's questions should be answered all the time and immediately. Rather, take the time to politely point the customer to the appropriate resource if it is a routine question or, in the case of a detailed "plea" for help or an issue (bug) with the software, make yourself available to assist the customer.

Along the lines of the above statement, it is completely valid and reasonable to expect the customer to provide a set of standard information in order to better assist them and their issue. I would suggest that a locked sticky be created (if there is already one, my apologies for not knowing...) which contains a post detailed the information required in order for help to be provided. Without this information, help cannot be provided.

4) Balancing on-line support with real life.
Having spent a number of years as a moderator on a very active forum Website, I certainly understand what it is like to have a full time job, a home life and THEN be expected to be available (for free) at a moment's notice and at a customer's beck and call. We all have real lives in addition to our on-line lives. Customer's MUST understand and respect the fact that the moderators on this forum are not being paid to provide customer service. Rather, they are providing this service from the goodness of their hearts and because they believe in their product.

A customer inquiry which requires an answer should be acknowledged and the customer notified that someone is looking into their issue. Some sort of timeframe would be useful to give to the customer as to when they can expect and answer. Any such timeframe, however, must be very flexible given people's own real life needs, wants and desires.


Okay. I'm sure I've "bored" y'all enough with my comments and suggestions. Let me close by providing an offer of help.

I certainly don't know the Calibre application well enough to act as an answer provider. I do have had several years of technical writing as well as technical training experience and am more than willing to help out with the documentation in order to provide our customers with material that is explained from both a practical and technical point of view.

Just let me know if I can be of help.

Thank you and, again, thanks to all the developers and programmers of this excellent application.

Regards,

[theducks]

Theducks is willing to help moderate. (like move a misplaced thread. Stuff I try and do now)

[Lady Fitzgerald]

Originally Posted by chaley

The first two lines from the wikipedia article on regular expressions (emphasis mine)

Regular expression

In computing, a regular expression, also referred to as regex or regexp, provides a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. A regular expression is written in a formal language that can be interpreted by a regular expression processor, a program that either serves as a parser generator or examines text and identifies parts that match the provided specification.

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.

An example of why is a recent thread I started regarding LN,FN in the author column and the tag editor. I quickly abandoned for now the idea of "fixing" my calibre installations because the thread became too complicated (for me) to follow even though I had asked for simple step by step explanations (I still have the thread, and others similar to it, bookmarked). Some of you have disparaged users who want a step by step explanation of how to do things but the fact is many of us NEED just that. I started using calibre simply because I needed a program that could manage my soon to be large collection of e-books (or pseudo e-books, as many believe image only PDFs to be ). Calibre meets that need for me better than any program I have tried, free or paid, and keeps getting better so, even though I do not understand half (or more) of its features enough to use them, I will continue to use calibre (and I have contributed financially so it's not like I'm freeloading) until something better comes along (something I'm not holding my breath for, even though one of the malcontents here claims he is writing a better one).

Frankly, I'm not interested on learning computer programming so I can understand the directions; I have other fish to broil (frying is too greasy). The difference between many potential users of calibre (and current users like me) and the power users here is many of us just want a program to do what we need it to without wasting a lot of time learning a lot of technical jargon and having to go through a bunch of complicated steps to to achieve our needs (heck, that's what the computers are for in the first place). Power users, on the other hand, seem to get off on complexity and technicality. I don't disparage them for it but, at the same time, I don't appreciate being put down for not sharing that fervor (however, I don't feel anyone here has done that intentionally or maliciously).

I use MS Word heavily. I had no trouble learning to use it, including some of the more complicated aspects, such as creating tables, framing for properly formatting text and illustrations, using enhanced metafiles for inverting text on pages that will befolded into small books (chapbooks), etc. even though documentation is almost non-existent. I was able to adapt to the new ribbon in Word 2007 without any problems.

Same goes for when I first got Adobe Acrobat Standard a little over a year ago. Despite it's reputation of being a difficult program to use, I hit the ground running with it and it quickly became all I use for working with PDFs.

I had little trouble learning to use the music notation program I used to use up to five years ago (I no longer arrange music). Back then, I was the one to turn to on the forum for that product for "creative" ways of getting the program to do things it wasn't really intended to do. I never had complaints from anyone that my directions were too difficult to follow nor that they were too simple.

Calibre, on the other hand, took a lot more effort for me to learn to use just the basic functions. It took what documentation it has plus a lot of help from folks here to learn how to use it at the limited level I'm at now. Even though most power users here will disagree, I find the GUI to not be very intuitive and, often, achieving a simple end, such as displaying authors as LN, FN, requires complicated means. The thread for creating catalogs was useless for me; I quickly became glassy eyed trying to read through it (granted, having ADD didn't make it any easier; too much data flowing through my brain at once shuts it down). Fortunately, I was was able to work out a Michael Mouse procedure that gave a usable PDF to use on my JBL.

That said, I must say that calibre, despite the fact I feel it is unnecessarily complex to use at times and the documentation difficult to use, is still an excellent program and the help I've received here is excellent. I don't expect any major changes simplifying the GUI and documentation anytime soon since a lot of effort is going into making calibre better and more useful and working on the GUI and the documentation would both divert effort away from improving the program and would require duplicated effort to constantly update both. I started using calibre last summer and the changes just since then have been phenomonal. I thank you all for that.

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

[Manichean]

I'd be willing to moderate the conversion subforum. And now I have to go read up on what happened in this thread. (Really, you guys, I go away from the computer for a few hours, and you just keep on writing )

[GRiker]

@LadyFitzgerald:

The thread for creating catalogs was useless for me; I quickly became glassy eyed trying to read through it (granted, having ADD didn't make it any easier; too much data flowing through my brain at once shuts it down).

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