Ok, pet peeve.  Rant.  Not directed to anyone in particular; especially 
not TLS, who took the time to explain things to someone who asked.


On Sat, 21 Oct 2006, Thor Lancelot Simon wrote:

> I tend to think that "How-Tos" are a very bad thing: they encourage people
> to do complex tasks, with potentially serious consequences, without the
> background knowledge they would have if they actually looked at the primary
> documentation for long enough to figure it out.  Then if anything goes
> wrong, they're utterly stuck.  The NetBSD Guide seems somewhat better.

   As someone who has actually had to learn things from scratch (as opposed 
to being born with perfect knowledge), I disagree.

   There are good how-tos and there are bad how-tos, just as there is good 
and bad documentation of any sort, including man pages and official 
guides.  A good how-to would give background on *why* things are set up in 
a certain way, and not just give a cookbook recipe listing the steps you 
have to take.

   That, IMHO, is vastly superior to some man page listing only the options 
a program takes (and still having to ask on mailing lists how things are 
connected); perhaps even better than an official Guide in which you just 
can't figure out *where* something is explained.


   And when you're learning about something, you often *need* a certain 
amount of hand-holding.  Sure, it feels nice figuring things out from man 
pages only, taking on the role of intrepid explorer of the 
almost-uncharted system in front of you.  But it's bloody annoying when 
you can't figure it out.


   Not to mention the times when you *think* you have figured things out, 
but missed a crucial detail and end up messing up the system (or leave it 
insecure and wide open).  A cookbook approach might even help in that sort 
of case.


  (And what about the times when what you are trying to do isn't considered 
to have anything to do with the operating system, and you need to browse 
pkgsrc for a solution?)


   I am not saying everyone should abandon writing all other documentation 
and start putting together their own pet documentation projecs; far from 
it.  But there is a need for documentation for people who aren't expert 
sysadmins too.  Just as there is a need for comprehensive reference docs 
as well.


   Don't knock howtos.  They do help.


MAgnus