FAQ vs Handbook (was: High levels of breakin attempts)

Erik Norgaard norgaard at locolomo.org
Tue Jan 11 01:45:52 PST 2005


Ted Mittelstaedt wrote:

> The FAQ and the handbook serve different needs.  If the official
> FAQ is got rid of then someone else will just write one on their
> website and post it because the need is still there - and the info
> on theirs could be pretty -wrong-.  It's better I think to have an
> official one even if every question is answered by "see section
> XYZ in the handbook, here's the link to it"

True, but what has happened is that what started out with simple 
questions and simple answers has evolved into pages and pages of 
documentation.

A question in the FAQ should be answered in one paragraph. If not, 
before adding a new entry in the faq one should ask: Are people asking 
this because it's not documented or documentation is badly written? If 
so, it's better to take a look at the appropriate section of the handbook.

> There's different ways of explaining the same thing, and an alterative
> way may be better for some people than others.  There's plenty of
> people who read my book and felt it explained things better than
> the Handbook, and vis-versa.  But both my book and the handbook
> had the same info in many cases - so what it boiled down to is
> that my style was easier for some people to absorb, the handbooks
> style was easier for other people to absorb.

Yes, sometimes it is easier to search questions - but having more 
sources of information introduces the risk of only one source being 
updated. Right now, you have the FAQ, the Handbook and the man-pages, 
keeping things in sync is a mess.

My personal oppinion is that instead of a completly separate FAQ, at the 
end of each section/chapter should be a FAQ. This would enforce the same 
organization of both FAQ and Handbook (which was one reason that the 
discussion arose) and it would be easier to merge things into the 
handbook when appropriate.

> You obviously forgot when you were in High School and the teacher
> gave the assignment for the next day, then at 2 minute intervals
> following this for about 10 minutes kids were asking "what's the
> assignment for tomorrow" ;-)

He he, my teachers were smart enough to write the assignments on the 
blackboard for that very same reason :-)

Now, I think this thread has gone too far off topic, so let it end here, 
I'll see if I can come up with an entry for the FAQ.

Cheers, Erik

-- 
Ph: +34.666334818                                  web: www.locolomo.org
S/MIME Certificate: http://www.locolomo.org/crt/2004071206.crt
Subject ID:  A9:76:7A:ED:06:95:2B:8D:48:97:CE:F2:3F:42:C8:F2:22:DE:4C:B9
Fingerprint: 4A:E8:63:38:46:F6:9A:5D:B4:DC:29:41:3F:62:D3:0A:73:25:67:C2


More information about the freebsd-questions mailing list