-----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... <snip/> > >> Just about every successful commercial product ever released has had >> books about it published *months to years* after the product was >> released. MS-Office tutoruals, RedHat administration guides, Hibernate >> "developers notebooks". Continuing the documentation process after the >> product is released is *normal*. >> >> > Not analog. Because other projects were bad, doesn't mean you should > aspire to the lowest common denominiator. Because there's a bum drinking > a 40 oz of Colt 45 out of a paper bag down the street doesn't mean > that's a good reason for all of us to do it. Okay... so I guess I missed the point here - when IS a good reason for all of us to do it? :-) Seriously I don't think the issue is that people are saying "they did it this way so that's the way we do it". Docs are good. Don't delay a release because there isn't any - just write it as part of the release cycle and there'll be no delay necessary. And putting my Jira where my mouth is, I've already headed over there to see what I can do to help (since I feel bad now having my Colt 45 wrapped in a paper bag out on the desk :-D) -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.5 (MingW32) iD8DBQFEDQujaCoPKRow/gARAjbsAJ4yNKnp7bNd2o1ANoEbEddtyaQS9gCfd5uT rdTEbUw3FZbgUsF1roFJ3qw= =T1OT -----END PGP SIGNATURE----- --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
