The Future of this Forum

[Manichean]

Originally Posted by cybmole

so a regular expressions for dummys intro sticky would be good. even calling it a regex is too advanced for beginners!

There isn't one because the thread that was started for the purpose of becoming a sticky got included into the manual. I thought that'd be enough visibility. I guess I was wrong.
Also, why call it anything other than a regex? That's what it is, and calling it "fluffy pony-rainbow-thingies" won't make it any less scary. Or, to put it different: Consider the regex tutorial. It tries to take users from the point of wanting to learn about regexes to the point of understanding them well enough to use them in Calibre. Obviously, you think it is too technical, but how would you improve it?

I like the idea of creating additional subforums, however, short of one dealing with conversion issues, I can't think of any topic that has enough traffic to actually merit having one.

[user_none]

I like Manichean's idea of having a guide for asking questions. However, there is a guide for getting a device supported and it's rarely followed...

[Manichean]

Out of interest, are there statistics as to how many people visit the help page or the manual on the Calibre site compared to how many people download it?

[cybmole]

Originally Posted by Manichean

Also, why call it anything other than a regex? That's what it is, and calling it "fluffy pony-rainbow-thingies" won't make it any less scary..

what it is, is a "regular expression"

"regex" is geek slang.

but even the correct name conveys no real sense of what it does, or why it is so useful.

with the 7.42 changes, I'd suggest calling the FAQ a search and replace guide. the fact the regular expressions are used to achieive this is an under-the bonnet syntax topic.
calibre has no screens called "regex"

PS
the excellent beginners book is called
"Sam's teach yourself regular expressions in 10 minutes"
not
"Sam's suggest regex and baffle everyone for 10 minutes"

PPS you asked how I'd improve it... maybe begin by paraphrasing the intro chapter called "understanding the need" form the above book.

I'll risk a single "fair usage" extract...

"Regular expressions are one of the most powerful tools available for text manipulation. The regular expressions language is used to construct regular expressions (the actual constructed string is called a regular expression), and regular expressions are used to perform both search and replace operations."

whoops that was 2 sentences - consider my card marked...

[itimpi]

The biggest issue that seems to be coming up repeatedly is a better way of navigating to required information, and then presenting the answers at a level that is appropriate to the navigation that was chosen.

Just a thought - there has been talk of a replacement for the FAQ thread? I wonder if that needs to be structured into some sort of giant Index where the top level gives you topic areas, and you drill down on them to other topics in the thread (which may then allow you to drill down further). Ideally the final level would basically be a link to the relevant section of the standard Calibre documentation, but if the required answer has not yet made the documentation it can be in a post of the thread.

My idea is that one would not ever read through the thread in order, but treat it is a series of "in progress" pages that will eventually be migrated into the standard documentation as they settle down and become more polished. Once a page has made it into the standard documentation it would either be removed from the thread, or that particular post marked as obsolete/supseded.

That would mean that we would still need threads about a specific topic that is under discussion, but ideally such threads would be focussed on a particular issue, and would naturally die when that topic reached its logical conclusion.

[kovidgoyal]

Hmm I was travelling last evening so I couldn't contribute. Here are some of my thoughts:

There is already a FAQ at http://calibre-ebook.com/user_manual/faq.html that I try to keep up to date as calibre evolves. However, I don't always succeed, and that FAQ covers relatively basic things as it is pretty long already.

In terms of stickies, I think we should dump the existing sticky structure and have something along the lines of

- A start here subforum with a few stickies that cover questions in commonly asked categories, and one sticky to give guidelines on how to ask a question.

- Three or four sub fora for the advanced topics: Recipes, plugins, plugboards, regexes?, conversions, catalogs? Each sub forum can have a couple of stickies for important/common topics.

What's needed to make this work is that a few calibre advanced users/developers volunteer to hang out in the sub fora of their particular interests. And it would be great if a few less advanced people would hang out in the start here/geenral forum and welcome/direct newbies to the appropriate places.

@Alex: Would it be possible to give a few volunteers moderator privileges just for this forum and its sub-fora?

I will volunteer to act as general backstop, trying to handle stuff that no one else can.

These are all just ideas, and I'm open to a completely different scheme if necessary.

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

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

[Manichean]

Originally Posted by kovidgoyal

In terms of stickies, I think we should dump the existing sticky structure and have something along the lines of

- A start here subforum with a few stickies that cover questions in commonly asked categories, and one sticky to give guidelines on how to ask a question.

- Three or four sub fora for the advanced topics: Recipes, plugins, plugboards, regexes?, conversions, catalogs? Each sub forum can have a couple of stickies for important/common topics.

What's needed to make this work is that a few calibre advanced users/developers volunteer to hang out in the sub fora of their particular interests. And it would be great if a few less advanced people would hang out in the start here/geenral forum and welcome/direct newbies to the appropriate places.

This sounds to me like a good idea.

[cybmole]

links to wikipedia in stickies could cover a lot of the terminology & syntactical bases

+ maybe a DON'T ASK section would be fun, as it could begin with the interminable requests to change calibre file structure... then continue to explain why various other "requests" will not be / can't be done - like DRM removal...

[chaley]

When considering this topic, one must ask the question "why would someone contribute?". There is only one reason: the person wants to do so. The reason for that want are as varied as there are people, but that doesn't change the fundamentals. My guess, based on nothing really, is that two reasons dominate. The first is the pleasure of solving problems. The second is the pleasure in giving help.

The first pleasure, problem solving, requires problems to solve. In such a context, explaining problem X yet again is not solving a problem, it is drudge work. The second pleasure, being helpful, requires positive feedback from those being helped. For some, a thank you is sufficient. For others, knowledge that a person learned something is sufficient. I am sure there are other motivations.

I know people who consider writing good (for some definition of good) documentation to be problem solving. However, most of these people do it for a living. For them to volunteer to write feels to them to be similar to a professional plumber walking around the neighborhood looking for pipes to fix. They would rather do something else with their spare time.

Every professional programmer that I know (and I know very many) excels in solving a variety of problems. They range across a large spectrum: how to do the job at hand, how to make it future-proof, how to accommodate the past, how to make it work efficiently, how to make it easy for the person who comes after, how to fit in with the 'culture' of what exists. Working through what something does and why it does it is a daily occurrence. Because of this, such people tend to have limited patience with people who won't put out the effort to figure out what something does.

Now, I can see the 'we are not all geeks' line coming at me. That is true. However, we are not all accountants, but if we want to avoid jail we must work out how to pay our taxes. We are not all professional chefs, but if we want an interesting cream sauce we must work out how to make a roue. We are not all professional drivers, but if we want to avoid being killed while driving in snow we must learn something about a car's dynamics. What I am getting at is that the vast majority of people are capable of learning something if they want to. My impression of the use of the 'geek' label, and the reason I don't like it, is that it is used to justify not wanting to; to say 'only those weirdos can understand that. We normal folk can't, so we don't need to try.' For me, this is painful on several levels.

OK, what does this have to do with this topic? Somehow, expertise needs to be connected to ignorance, in such a way as both the provider and the recipient are satisfied. Achieving this requires mutual respect, and support for the people donating their expertise. Getting snippy and saying RTFM (and yes, I know I am very guilty of that) is not showing respect to the asker. Saying "Urk, that is too complicated. Just give me a solution" or "why can't you describe it in a useful way" is not showing respect to the provider. I hope that whatever solution is contemplated will take this into consideration.

[Starson17]

Originally Posted by chaley

When considering this topic ... <best parts deleted>

Nice post.

[Manichean]

Good post, Charles, and some very good points. I assume that most of the people act out of both motivations to help.

I see splitting the forum into some subforums to accomplish this job: In the general forum, there'd be some general stickies as well as one explaining how to meaningfully ask for help, the subforums would have more specialized stickys (most of them still to be written). If we had maybe two or three people with at least the authority to move threads inside the Calibre forums, everything could be kept relatively tidy. The users would then, from the main forum, see where they would need to go to ask questions, and the regulars could choose which forums they'd like to or feel comfortable to help in.
This, of course, assumes that the person asking to help is actually willing to learn something. I don't know how to work around it if they aren't.

[user_none]

I only see splitting into sub fora if you cannot post in the calibre top level forum. If you can still post in the top level forum no one is going to bother posting in the correct sub fora. I can see the thought process as, "Why post in sub x when more people will see it on top." and "Choices? how about I not choose and just put it. under calibre."

[Manichean]

Originally Posted by user_none

I only see splitting into sub fora if you cannot post in the calibre top level forum. If you can still post in the top level forum no one is going to bother posting in the correct sub fora. I can see the thought process as, "Why post in sub x when more people will see it on top." and "Choices? how about I not choose and just put it. under calibre."

That's a valid concern. However, there will, I think, always be topics which don't fit any of the subforums. I don't think we could totally lose the ability to post in the main forum.