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@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-list Guidelines: http://fedoraproject.org/wiki/Communicate/MailingListGuidelines
