Date: Fri, 16 Mar 2001 22:21:19 -0600 From: Mike Meyer <mwm@mired.org> To: David Johnson <djohnson@acuson.com> Cc: questions@freebsd.org Subject: Re: documentation issues generally Message-ID: <15026.58943.554108.688513@guru.mired.org> In-Reply-To: <22787522@toto.iv>
next in thread | previous in thread | raw e-mail | index | archive | help
David Johnson <djohnson@acuson.com> types: > Ted Mittelstaedt wrote: > > I disagree with this. Rather, the problem is that programmers usually > > dislike > > "wasting time" on writing documentation. All of them that I've worked with > > are more than happy to have someone else do it. But, I've not sensed that > > anyone I've worked with has "looked down" on what I'm doing. > It's not that they consider it "wasting time", it's just that it's pure > drudgery. I've written documentation for my own programs, and am > currently helping with docs for KDE. It's not fun. It's boring. The > developers should be the ones writing the docs, since they know the > software the best, but they will probably be the ones least likely to > enjoy writing it. This is a base canard. Just because someone is most familiar with a bag of bits does *not* mean they are the ones who should be explaining it to others, or the ones who are best able to do so. Otherwise, you'd argue that Einstein should have taught froshling physics. The first problem in this case is that the ability to write C well (or Python, or Perl, or anything else except maybe COBOL) does not infer the ability to write English well. In general, the opposite seems to be true - the better code someone writes, the worse documentation they'll write. Before anyone gets offended, that's a *general* trend, and does not necessarily apply to any individual. But those who excel at both are rare and very valuable. The other problem is there is a natural tendency to explain what the author needs to know to use a program. This is a short list for someone who's been working with BSD daily for 20 years. It's a much longer list for someone who's on their second install. It's a very long list indeed for someone who has as yet to find the power switch on any computer. It's an intractably long list for someone the author doesn't share a natural language with. One of the things that make good documentation people rare is that the ability to find an appropriate level of previous understanding to assume is uncommon. Having worked with a number of groups that provided rather technical products (enterprise level servers, for example) and their documentation, there are a number of common elements. One is that the documentation group was composed of different people than the implementation group. The other is that there were several levels of documentation, aimed at people with different levels of prior knowledge of the server. FreeBSD is pretty much a completely volunteer project. The only way to get better documentation is for someone to step up and *write* it - and then submit it back to the project. There's lots of things to work on; just choose one and have at it. <mike As an aside, should someone think that programmers not being able to write English well means programmers are dull/stupid/uneducated/whatever, contemplate how few writers can program *at all*, much less well. -- Mike Meyer <mwm@mired.org> http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15026.58943.554108.688513>