OT Humble Pie

[Frans-Jan v. Steenbeek]

At first: understandable documentation should begin at the beginning (and it
won't be perfect, I know).
Second: the people complaining about the documentation are newbies with
FreeBSD (like me) and many times newbies in the Open-Source community (like
me). Writing documentation is then just a few steps too far away.
Third: on many issues good documentation exists but is NOT included in the
packages (I think because they are mostly not entirely complete).
Making a good documentation wich is understandable AND complete is almost
impossible, so maybe the goals should first be changed. IMHO the concept of
"man-pages" is as good as outdated as GUI-enviroments become more popular.

People are often complaining that the "Unixxes" should make themselves as
user-friendly as Window$ is. That is not possible (because doing so simply
creates bugs) but things can improve. Documentation is a good thing to
start with. I have not the skill to do it, else I would already have
created a concept.

On Mon, 31 Mar 2003, CARTER Anthony wrote:
> Date: Mon, 31 Mar 2003 10:14:20 +0200
> To: freebsd-newbies at freebsd.org
> From: CARTER Anthony <a.carter at cordis.lu>
> Subject: Re: OT Humble Pie (was hardw words)
> 
> IMHO (In My Humble Opinion), if anyone has any gripes with the language
in the 
> documentation for freebsd, instead of complaining to FreeBSD mailing
lists, 
> they should get involved with the documentation projects and write an 
> "understandable" version. I don't mind people complaining about things,
> but  instead of just complaining, suggesting changes would be more useful
and,
> I  guess, very welcomed.
> 
> So, next time you find a complicated man page or technical article, find
> out  the answer by asking questions on mailing lists etc., figure out
what it 
> means, and then re-write the documentation in a way that you would find 
> useful for others in your situation. Then submit it for approval and
> basta,  everyone profits. In the end, with everyone doing just a little,
the 
> documentation could be vastly improved for non-technical people.
> 
> Anthony Carter