Using Wikis for documentation

At work we use Confluence, an Enterprise Wiki provided by the cool people over at Atlassian. The idea being that documentation can be added to the wiki where it can be easily updated, accessed, commented on clarified etc.

The added benefit is that Confluence allows you to subscribe via RSS to various parts of the wiki - this can be quite useful if you are still in an organisation and want to monitor changes and updates. For example if someone posts a comment asking a question about some of the documentation I can see that in an RSS feed (or via email if I choose) and I can spend 5 minutes updating the doc to either answer their question or clarify the page in question. In essence (provided the wiki evolves with the system) it allows the original developers and designers a way to monitor the evolution of their system even though its been handed over (I’m assuming here that the original developers/designers still have access and have an active interest). This is beneficial because it allows you to asses whether the design decisions made stand the test of time and to reflect on your architecture.

Some people have commented that wikis do not lend themselves well to versioning.- yes you can review the changes to a particular page but how do you know what version of the wiki pages relates to which version of the system?

I think the way to approach this is to simply have a wiki per version.

There was one thing I have been always conscious of and that is having bits of information everywhere - we have code comments, unit tests, wiki documentation, issues in our issue tracker, cvs commit messages.

And just like we all know duplication and redundancy in code leads to maintenance problems, the same applies equally to code documentation. The one thing worse than no comments is outdated or incorrect documentation which conflicts with other documentation.

Here is how I typically address this and where what I place where:

Readme.txt – documentation on installing/building a project once checked out of source control 

Source control commit comments – explain what was changed with an issue number which refers to the issue number in the bug tracker for an explanation of the bug/issue/enhancement

Issue tracker – Bugs or enhancement requests 

Cfcdoc – Api documentation as this is based on the version of the code checked out there are no issues with this being out of date.

Other documentation – Wiki where it can be searched, commented on, printed out, linked to etc.
 

If changes are made to a system due to a bug or an issue with the design - I find it better to simply provide a link to the issue in Jira (the 2 products integrate well) rather than update the wiki and have the same information in 2 places.

You'll notice in the above one glarying ommission and that is database documentation. I'm still not 100% sold on a good way to do this - perhaps I haven't found a sufficient tool. Many databases do allow you to store comments against items in the schema and we tend to store a database creation script under source control as well.

links: digg this    del.icio.us    technorati    reddit