Ara [Memory Dump] makes some great points in Sketching Sequence Diagrams With Text. Open source projects tend to have great technologies and code but seriously suffer in the documentation department (especially the projects I work on :-).
I'd love it if open source projects used a kinda wiki/blog to create, edit and maintain its documentation. Though I do find all the various Wiki formatting conventions to be a little bit of a pain - I'd much rather just take advantage of the rich editing widgets in IE & Mozilla and other HTML editors so that folks spend most of their time just editing HTML in a WYSIWYG fashion rather than having to remember wierd character sequences just to turn things bold & italic.
Also the lower the barrier of entry to getting folks to contribute to a project, the more chance there is that folks actually will contribute.
I also like Ara's point about using the same Wiki mechanism for editting other custom text formats such as the texual definition of UML models to include in the documentation etc.
Here's my wishlist for the ultimate wiki-documentation tool for use by open source projects...
- I'd like to use mostly WYSIWYG editing of HTML for most documentation
- I like the shortcuts feature of Radio (you can have a list of named bookmarks and use them by just quoting words in the documentation).
- I'd like the Wiki to store the documentation inside CVS so that it can be included in releases and can be used to roll back changes and maybe authenticate editors
- Storing (or at least generating) an XML representation of the documentation so that it can be rendered in various formats maybe by the build or release system
- Support directories to categorize documentation (unlike many wikis)
One day it'd be nice if open source projects used a combination of wiki and blog for project news, design documents and documentation.
3:02:38 PM
|