<quote src="http://www.keelframework.org/mission.shtml"; > Anti-Pattern: Documentation Problems
The best feature of open source is also its downfall - wildly varied forms of documentation, with its most important form also being its most problematical - mail lists. Funny thing is, most of the time it isn't just a lack of documentation, there is usually too much, and you can't find what you need without going through email archives for hours at a time. Solution:
Keel attempts to reduce documentation to javadocs, and online FAQ's editable by users, such as with Wiki. Email is the big problem, and we request users to not use it for documentation - if you answer a question, answer it in the Wiki FAQ, and use email only to furnish a link to right place in the Wiki FAQ. </quote>
Do we have this problem?
yes, and I think its actually a big one throughout the software world (not just open source). Wikis are one form of knowledge management tool that can work well. I've also seen knowledge management tools with e-mail support; actually, I built half of one of those about a year ago. I think the key is finding a way to combine the free-formness of the wiki with the "direct communication" feel of the mailing list.
Forcing everyone to use wikis only is a problem as well: I think many people will not even attempt to use the project in that case.
It should be possible to "reply" to the addition of a question on a wiki, to be able to "comment" on wiki pages via e-mail, etc etc. I don't think any current wiki has an e-mail interface, though.
cheers!
- LSD
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
