MediaWiki for project documentation

As Joel points out, "Writing specs is like flossing: everybody agrees that it's a good thing, but nobody does it". Programmers prefer to express themselves in code rather than documents.

I have seen two extremes in software documentation. I used to work in a Big-5 consulting company (it shall remain unnamed) where everything had to be documented and approved before the first line of code was written. This is partially because you need some protection against scope creep which will surely happen: no client knows what they really need before the project is almost finished. This is also because big consulting companies sell CMMI processes for a living, not to mention that they now all outsource the actual development to India, keeping only requirements, architecture and QA in-house (so much for time to market).

I think of CMMI as project managers spending too much time thinking about their work, rather than actually doing it. The equivalent for software architect has to be Model Driven Architecture, i.e. software programming without programmers. Interestingly both target the same market: your CIO and IT managers.

The other extreme is of course no documentation at all, not even functional specifications. "Our job is to write code, not documents!" Yeah, right. The only time Agile Programming does not equate cowboy coding is when the team is very small, composed exclusively of very senior developers and when time to market is the main business concern. In my experience, in any other situation Agile Programming becomes Fragile Programming, delivering pieces of software only maintainable by their authors.

There has to be a right balance between time to market, maintainability and reliability which is to be defined for each project. I personally like RUP but only if I can pick and choose from RUP what is really useful for my project (applying RUP without tailoring is nonsense). No RUP deliverable is really mandatory for all projects, not even Use Cases. What is needed really depends on the scope of the project, as well as on who you have in your team.

I recently experimented with MediaWiki to build a software documentation repository for all projects in my group. We used to keep all our project documentation in MS Office documents stored in Sharepoint, which doesn't provide more functionality than a hierarchy of folders on a shared drive (it actually stores documents in SQL Server and you can choose to browse or search with using the most unfriendly web interface or with File Explorer).

MediaWiki is the open source software that runs Wikipedia, so our project repository looks like a small Wikipedia web site. It is a breeze to install provided that you have a Linux box and a MySQL database. It works very well and everyone likes it:

• It makes it very easy for everyone to write a note about how to deploy a piece of software or to document a process. It is also easier to find information.

• You don't have to be as formal as with Word documents.

• It's fun to use! (not like flossing)