One quickie reply:
Brian K. Wallace wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Brad O'Hearne wrote:
<snip/>
And fourthly, the developers are often *not* the best people to write
the documentation. For someone who knows all the details of an
implementation it's quite hard to step back and write good introductory
tutorials.
Absolutely they are. Especially in open source, they are the ones who
know how something works, and is supposed to work. You cannot have
someone who doesn't understand the product document it. What you are
referring to is the inability of many developers to communicate concepts
effectively, which is an entirely different issue. If a developer can't
communicate their thoughts, well then, that's something they need to
work on. But it doesn't mean you lower the bar on your project.
I'd have to disagree on this one. I'm all for documentation, etc...
matter of fact I agreed with most of your other thoughts... but there
are two (at least) different 'levels' of documentation. Pure "user
level" documentation is not usually well written by the person(s) who
wrote the code. But then again, I wouldn't want the person who can write
good user documentation to write the javadocs, either...
You are talking about the difference between an author and an editor to
some degree. A developer has to document, and that includes being able
to impart in some form user level documentation if it pertains to what
they worked on, even if someone else reshapes that into something
prettier for general consumption. If the developer is unable to
effectively communicate their contribution, then that is not an issue
which should alter the project approach; it is an issue which should
alter whether that developer contributes or not. I find it personally
hilarious that we place as a prerequiste for a developer fluency in the
language of Java or C++ and completely discard fluency in the language
of English. Communication isn't some kind of optional "nice to have";
its a necessity.
Brad
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
