right tutorial

[Alan DeKok]

On Jun 26, 2018, at 12:50 PM, Anthony Stuckey <anthonystuckey at gmail.com> wrote:
> Reading the docs is often like trying to learn English by reading the
> dictionary.  I know what Nouns, Verbs, and Adjectives are, I don't know
> what a sane sentence structure is or how to write a poem.
> 
> There is only so far most people can go on their own.  Frustration is not a
> learning technique.

  People get told "read the docs" when the documentation has answers to their questions.

  If they have specific questions about what they read, or are uncertain about the docs, they are welcome to ask more questions.

  We *never* tell someone "read the docs" when the answer isn't in the docs.

  We *never* tell someone "read the docs" when it's clear that they HAVE read the documentation, and that they find it lacking.

  What you're asking for (implicitly) is documentation that tells you how to configure the server to do what you want.  Sadly, this is largely impossible.

  There are many "how to" guides for simple / common situations.  That documentation is pretty decent, and few people have pointed out errors or omissions in those pages.

  Once you're into custom / complex configurations, you *must* put the pieces together yourself.   The following items are important:

1) you need to explain what you want to do, in detail.

  Many people fail here.  "I want to do stuff" is not a good explanation.  Much frustration is seen here when we go "please say WHAT you want to do", and people respond with "You're the experts, you tell me!"

  it doesn't work like that.

2) explain what you did

  Many people fail here, too.  "I did stuff and it doesn't work" is a terrible post to a mailing list.  It's been in the FAQ pretty much since the beginning of the project

3) follow instructions on the mailing list

  Honestly, if you ask a question and get told "post the debug output", you shouldn't do anything OTHER than post the debug output.  Arguing about it, or doing something *else* is a guaranteed way to frustrate everyone.

  The same applies for other instructions.  If you get told "post what you've put into SQL", then you should post the SQL data.  Any other activity is anti-social and rude.

4) Nothing else.

  That's really it.  If you follow steps 1, 2, and 3, then you *will* get your problem solved, and you *won't* get too frustrated.  And neither will the people answering your questions.

  The sad part about this is that when I write such lists and give explanations, people complain that it's a series of "holier than thou" comments which put down the questioner.  You just can't win.

  Alan DeKok.