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.
Actually Marco, I have written many documents, and am a pretty decent
technical writer within the area of my particular expertise. I am a
Test Applications person who wrote over 60 programs for Teradyne Inc.
along with several hundred pages of documentation on system use and
technical skills for test applications. You would find some of them in
nearly every company in the world using Teradyne systems. I wrote and
delivered training on RF, Video, DSP, system correlation, and several
other topics, and no one ever complained that they didn't get their
money's worth.
Yet even my documentation was often improved upon by those who followed
later. That is engineering in progress. Some of those changes were
patently wrong as well, and often what the uninitiated see as a failure
of the documentation is really a failure in following well what was
written. In many cases the folks who criticize documentation haven't
actually read it. I read nearly a 1000 pages a week of technical
documentation, and that is what makes me good at what I do. The field
for Technical topics is not ever static. During my career, from vacuum
tubes to DTL, then TTL, then MOS, then CMOS and advanced BI-CMOS, some
DMOS, and of course the advanced processes today where devices are so
small that you practically need a microscope to read their labeling, the
field has continually advanced. Advanced architectures today for
software, hardware, and OS's are changing at an increasing rate, and
have been for decades. It won't stop, or get easier, but only
magnitudes of more difficult if you do not keep up.
When you talk about how "docs are broken", and then refer to Wikipedia,
you are not looking at true technical documentation, but historical
documentation, and there is a real difference. What is needed for
technical documentation is indepth knowledge of not only how a system
works, but why, and why you should not "short cut" the means and methods
supplied. Does that mean that everyone will read the documentation? Of
course not, and of those who really read the documentation, how many
will actually act according to the document?
My experience is that at every engineering site, there are one or two
"guru's", and they are the ones who actually do the grunt work to
understand how things work. They read the documents. Most of the rest
to some degree piggy back on those few. That's not bad either. It is
human nature. The best companies find out the best capabilities of each
and capitalize on them, as well as working with their weaknesses to
improve the people within the company. The most successful companies
leverage that expertise across their customer base and across product
lines. And that leveraging is accomplished through abbreviated
documentation targeting specific needs, along with specialized focused
training.
I am unsure how to accomplish that in Fedora, but it is a worthwhile
goal.
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
