Peter Jeremy wrote:
On Wed, 2005-Dec-07 13:34:53 -0800, Vizion wrote:
That is a judgment call - franky my experience has been that developers who
are bad at ensuring their work is well documentated are second rate rather
than top rate developers.
Software developers are notoriously poor at writing documentation for
non-technical people. There are probably very few developers who
enjoy writing end-user documentation (and can write).
My personal expectation is *not* that the FreeBSD developers tell me
what a cdrom is. My expectation is that they tell me what works, what
doesn't, and warn me about whats in the middle. Trust me, there are
damn few "non-technical" people installing FreeBSD, and I'm pretty sure
both of them gave up in sysinstall. I can read (most) code and I can
search PR's. However, if it's 2 am and my server has puked on it's
shoes during an upgrade due to an undocumented issue the developer knew
about, I'm not going to recommend FreeBSD to anyone other than as a
hobby for single men with beards.
In my
experience, especially on large projects, it's rare for developers to
write the end-user documentation. They may write a rough outline but
it's the technical writers who actually do the documentation. The
problem is finding people with technical writing skills who are
interested in helping with FreeBSD.
It's also worth noting that a number of FreeBSD developers are not native
English speakers. It's probably unreasonable to expect them to write
polished English documentation.
Again, I'm not asking them to write chapters in the handbook and I
understand (and assumed) they may not be native English speakers. How
hard is it to get a, "ata.c broke with via 666 sata chipset under heavy
load"? If I have a via 666 sata chipset, now I know to go looking in
the code. Even if don't go looking in the code, I know that I might
want to look at a different adapter. Don't tell me whats little more
than a subject line of a mail message is beyond even a junior
non-English speaking coder and a few minutes with a translation program.
Are you volunteering?
Yes, I'd like to help, not that I think my writing skills are all that
great. But "no" if the developers won't be forthcoming with details.
P.S. I'm not picking on the ata code or it's owners. It was just a
module name I knew off hand.
jim
_______________________________________________
freebsd-stable@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-stable
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
