[Tutor] Comment on http://www.catb.org/esr/faqs/smart-questions.html

[Rick Moen]

/me waves to esteemed tutors and helpers.


Quoting Bob Gailer (bgailer at gmail.com):

> I have a reaction to 
> http://www.catb.org/esr/faqs/smart-questions.html and I'd like your 
> feedback. Perhaps I will then send revised comments to the authors of 
> the [essay].

As one of the essays' co-authors, I'm always interested in thoughts,
especially ones about how to improve the fool thing.  (As you'll see
below , I have more than a few, myself.)

> I found myself a bit disappointed. 

Me too.  (No irony intended.)  Eric and I never quite achieved what we
hoped with it.

> All I see at first is email links and Revision History. If I did not 
> know to scroll down I might have just figured I was at the wrong page.
> 
> Reading translations and disclaimer is not why I'd come here.

Personally, I'd have tried to put the links to translations and the
revision history at the end, if possible.  Eric maintains the master
version, and IIRC uses a Docbook XML toolkit with a precooked
stylesheet.  I've never personally tried to significantly hack such
tools to customise presentation.  As maintainer of one Linuxdoc
SGML-format FAQ and one Docbook SGML-format HOWTO for the Linux
Documentation Project, I've long been a bit dissatisfied with the
somewhat inflexible document structure the related toolkits push authors
towards.  Perhaps Eric found likewise; I'd have to ask him.

Anyway, my point is that as an author, I'd generally rather spend time
writing than hacking madly on document-production tools to rearrange the
elements and alter the presentation.  Time permitting, I do hope to get
around to working with Eric to see if the order of elements can be
rearranged with reasonable ease.  However, there are much larger
problems, which I'll get to in a minute.

> With contact names and email at the bottom

Objecting to e-mail links' living at the top doesn't seem
reasonable, sorry.  Those are merely the names of us co-authors.
If it really bothers you to see authors' names at the top of what they
write, Bob, you might want to quit the habit of reading before you
become truly vexed, as you'll see it more often than not.  Books in
particular are going to be a huge disappointment to you.

As to the 'disclaimer', can you guess _why_ it is there?  

Let me tell you, sir:  For over a decade, every single day of every
single year, I get at least a half dozen misdirected helpdesk requests
in my personal e-mail.  Most are for technical projects (mostly
software, but not always) I've never even heard of.  Often, they are
demanding and downright rude in their insistance that I help the querent
with $FOO for some bizarre value of FOO _right now_.  I'm always nice to
them and try to send them in the right direction, but _man_....

The 'disclaimer', the bit that says that Rick and Eric are not a
helpdesk for several thousand projects they (mostly) haven't even heard
of, and please for gosh sakes avoid pegging the irony metre and
send your help requests to the right place, has cut the daily inflow.
I used to get several dozen per day.

I'm sorry you're annoyed by seeing it, but not moved to think it's a bad
idea.  Rather the contrary.  If anything, I'm pondering the virtues of
<blink> tags and red text, man.[1]


> There's a lot of words to wade thru 

Exactly.  That is the biggest problem, and it's fundamental such that it
can be addressed properly only through a do-over.


Let me recount what happened.  Around 2000, Eric and I became aware that
we were more-or-less writing the same sort of essay (except Eric's
wording is pitched as advice to those seeking technical help from
'hackers', while I just was generically talking about online technical
help).  We joined forces, with Eric keeping the master copy and using
his document-production toolchain.

We put out a nice -little-, tightly focussed essay.  To our
astonishment, it proved very popular.  Thousands (at minimum) of
technical projects linked to it from their help pages.

Correspondents kept asking us to add things:  'You should also cover
$FOO.' We're obliging people and tried to accomodate most such requests.
And they kept coming.  Lather, rinse, repeat.  Over ten years later, we
now realise to our dismay:  no more nice -little-, tightly focussed
essay.

What can I say?  We tried, we wrote, people asked us to add more, we
obliged, and the results have gradually become bloated.  (Tolkien said
'It grew in the telling.'   Ours did, too, albeit there the comparison
ends.)

Moreover, it's an unsatisfyingly linear piece, which is not really what
is needed.  _That_ along with sheer bloat makes it, IMO, fail at its
original goal of helping frustrated and impatient people deal better
with techincal projects' online help forums.

So, I've been wanting to sit down and start over from scratch, and this
time write a nice -little-, tightly focussed essay using a radically
different format of some drill-down-for-more variety.  Some toolkit
hacking may be required -- or maybe just roll my own, in Python,
starting from something like ReST rather than overengineered XML stuff.
But I've not yet had time.

Meanwhile, we're absolutely delighted when other people think they can
do better, and enthusiastically encourage them to do so.  I'm personally
a big fan of Java Ranch's nice -little-, tightly focussed essay for
people asking questions.


> I also would not have come here to be potentially labeled an "idiot".

Being a naive and cheerful optimist, I hope and expect you eventually
noticed that Eric's and my essay neither stated nore implied that anyone
is an idiot, Bob.  We didn't even imply that idiots are idiots.

Anyway, thank you for your thoughts.


Quoting Emile van Sebille (emile at fenx.com):

> In any case, I wouldn't write esr and Rick Moen to request changes --
> I expect you'd be pointed to 
> http://www.catb.org/esr/faqs/smart-questions.html#disclaimer if you got 
> a reply at all.

We try to give thoughtful responses to anyone who writes us about the
essay.  After all, we share their desire for it to be useful to people
(which is why we goodnaturedly kept adding more and more coverage to it
upon request, although in retrospect we probably should have politely
said no).

Quoting Steven D'Aprano (steve at pearwood.info):

> But really, I want to re-write them both [How to Ask Questiosn the
> Smart Way and Short, Self-Contained, Correct Example] for a Python
> audience. One day, when I get a round tuit.

Please do.  (Those circular tuits are scarce, I notice.) 

> In my feedback below, I'm going to attempt to channel ESR,

As the saying goes, Eric's co-author is not chopped liver, by the way
(but he is not taking offence).


[1] If not ALL CAPS BOLD ITALIC RED TEXT WITH GREEN UNDERLINED 
SPACES BETWEEN WORDS.  (Yes, I'm kidding.)