On Sat, 2008-12-06 at 19:22 +0100, M. Fioretti wrote:
> On Sat, Dec 06, 2008 09:31:55 AM -0800, Les wrote:
> > On Sat, 2008-12-06 at 12:04 +0100, M. Fioretti wrote:
> >
> > > 1) be ABLE to write good documentation. You yourself acknowledged
> > > good "documenters" are scarce. You're either good at it or you
> > > aren't, it's just like programming or any other complex
> > > creative activity.
> > ....
> >
> > I haven't written anything for LINUX, but I can tell you that the
> > biggest issue is getting "something" on paper (in bits?). Once the
> > first effort is in, LOTS of people can "fix it" and even copy it and
> > redo some or most of it... That's OK, if your intention is to get
> > information into the Linux sphere.
>
> I was **explicitly** speaking, see the quote above, of **good**
> documentation. And since I already wrote how weak I find assumptions
> like yours above, I'll simply point you to Point 1 of
> http://digifreedom.net/node/61.
>
> > So, my advice is "just do it". someone will fix it.
>
> Here I could simply answer "after you, please" or repeat what I wrote
> above: we're talking about quality, not quantity. But I have a very
> fresh, real world example of somebody who "just did it" and things
> didn't go as you say, so I'll let that speak for itself. Have a look
> to the thread about Postfix How-tos starting at
> http://archives.neohapsis.com/archives/postfix/2008-12/0133.html
>
> the thread summary is:
>
> - postfix gurus only wrote good, but too difficult docs
> - some popular postfix howtos (by other people who "just did them")
> are broken
> - newbies read **those** docs only, as the "official" ones are too
> difficult
> - they make mistakes following those docs, ask how to fix them to the
> postfix list. This happens several times a year.
> - every time, postfix gurus answer "those docs are broken, check the
> official docs"
> - for any number of reasons, postfix gurus have no plan to write better
> howtos themselves
> - nobody but postfix gurus could write better howtos than those
> already available, or fix those ones. Excepted a good technical
> writer **paid** enough to spend on the subject lots of time, since
> it isn't an easy task by any means.
>
"since it isn't an easy task by any means" is the statement I hear a
lot. The truth is that writing should be part and parcel of every
engineers job. However it is seen as "grunt work" by many young
engineers who have not been well exposed to the need for documentation
within their education. Programmers are taught "self documenting
code"... What an oxymoron. We do call it code for a reason.
Hardware and software engineers are not well educated in the need for
documentation, and seldom given any time at all to do that portion of
the job. If you take time to do the correct support task some fool that
doesn't know anything about the task, the skills, the knowledge, or the
overall expertise of state of the art will criticize it. As a result
you get bad support, poor products, and the inability to transfer
knowledge. Read the documents on ANY software package built on "object
oriented code", and tell me how many bits of the data, code and
operation are required to actually accomplish the given task, or how it
can be improved. Ever tried to optimize object oriented code? I have.
There are a lot of educators on this list. I hope they read my last
post on this and this one. Our societies depend upon the software and
hardware being designed and built today. Your cars systems, aircraft
systems, medical systems, alarm systems, communications systems are all
becoming vulnerable to loss of knowledge and expertise.
Sorry Marco, just one of my pet peeves.
Regards,
Les H
--
fedora-list mailing list
fedora-list@redhat.com
To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-list
Guidelines: http://fedoraproject.org/wiki/Communicate/MailingListGuidelines
