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