Date: Sat, 04 Dec 1999 12:57:09 -0500 From: Bob Johnson <bjohnson@gainesville.usda.ufl.edu> To: "stable@FreeBSD.ORG" <stable@FreeBSD.ORG> Cc: god@yahoo.com, bjohnson@gainesville.usda.ufl.edu Subject: Re: bugs in the handbook. (FreeBSD Portal) Message-ID: <384955F4.DDD4FCD7@gainesville.usda.ufl.edu> References: <c=US%a=_%p=USDA%l=USDANT299122610518TYYSB29@gainesville.usda.ufl.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
stable-digest V4 #592 contained the following:
> Date: Sat, 25 Dec 1999 01:21:21 -0800 (PST)
> From: Mike s <god@yahoo.com>
> Subject: Re: bugs in the handbook. (FreeBSD Portal)
>
> well yes i agree that the linux Documentation project
> is along the lines of what i am talking about, but
> again take linux.com for example. IF we had volunteers
> who had knowledge of the latest web development
> resources/languages such as sPHP we can start a site
> that is based mostly on volunteers as is linux.com
>
> Awhile back, there was a discussion on this questions
> and this mailing list about not nearly enough newbie
> documentation. So i guess we are a lacking in a few
> areas.
>
> but, its planting the seed that counts.
>
> again, not to compete at all with freebsd.org a
> separate entity entirely.
>
> besides, a lot of people who would commit to -docs
> don't have the knowledge or patience to learn the SGML
> structure if the site itself.
>
This isn't the obstacle that many think it is, because there are
people who are willing to take text contributions and add the
necessary SGML. By far the hardest part of producing
documentation is coming up with the text in the first place.
Once someone has figured out what to say and how to say
it, the formatting details can be worked out by someone
else who specializes in that.
Since the -doc group is working on cleaning up the Handbook
so it can be published in print in the (near?) future, right now
would be a good time to write any documentation you are
capable of and submit it.
>
> I'd like to see a site going up utilizing php/mysql
> for fast and convenient site development.
I think it makes more sense to put the effort directly into
improving the Handbook, but if an alternate approach
gives us better documentation, that's what really counts,
so I think your "experiment" is well worth the effort.
> [...]
>
> - --- Colin <cwass99@home.com> wrote:
> > I don't think we don't care about the
> > documentation, that strikes me as
> > something of an oversimplification. There are 2
> > distinct problems here:
> > 1) The peole who know enough about the system to
> > document it properly
> > generally don't have the time (or
> > inclination...gotta love those programmers ;))
> > to spend on documentation. They're too busy fixing
Most non-programmers (or, more accurately, non-documenters)
don't understand that it takes roughly as long to properly document
a program as it does to write it in the first place. It isn't
usually the most effective use of resources to have the
original programmers producing the documentation, because
the skills required are not the same.
I mention this as a means of encouraging anyone who is able to
submit additions to the FreeBSD Handbook. If you know how
to do something that isn't documented, write it up and submit it.
Someone will pick it up and add the necessary SGML to
integrate it into the Handbook.
> [...]
> > 2) The peole who are most willing to spend time on
> > the documentation don't have
> > the specific knowledge to do it. They are the one's
> > who would like to be
> > reading the docs.
That is, of course, the tough part. I've found that most
programmers are happy to answer specific questions if
it reduces the overall effort they have to devote to
documenation. If you can read the code, or other docs,
and figure out most of it, there's nothing wrong with
asking the code maintainer to explain the remaining
details so you can get it documented.
> [...]
Of course, all of this is my personal opinion and I don't
speak for the code maintainers or the -doc group.
-- Bob Johnson
bjohnson@gainesville.usda.ufl.edu
bobj@atlantic.net
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?384955F4.DDD4FCD7>