Since my current project is coming to an end, it's a good time to look back at our project blog to review the type of content that we captured during the project. As I've mentioned before (Blogs and wikis, Project Blogs, Blogging your build and Blogs as extreme feedback devices), I started a project blog so that we could capture all of those little snippets of information that typically float around in our heads but rarely get written down anywhere because they might not been seen as core to the success of the project. In addition to this, I configured CruiseControl to publish build information to the blog. To give you some background, we were a self-contained Evolution team, made up of a project manager, technical architect (me) and 3 developers. The project itself was around 3-4 months in duration and we were based on the client's site.

I did a presentation a couple of weeks ago that summarized the best practices that we used throughout the project, with emphasis on automated unit testing, continuous integration and project blogs. One of the key messages that I tried to get across was that these are very powerful yet easy to setup, without the need for a dedicated box. CruiseControl, Tomcat and Pebble were actually hosted on my desktop PC. With free software, free hosting and practically zero maintenance, the benefit of this simple setup was huge. So then, what sort of information did we manage to capture? Here's a summary.

• Client specific information (e.g. internal phone numbers).
• Links to project artifacts and announcements when they were released.
• Screenshots of the application, showing progress and new features.
• Client sign off announcements.
• Explanation of the UML model organisation.
• Eclipse project structure and configuration.
• Eclipse code formatting rules.
• Build file details.
• CruiseControl setup.
• Config file details.
• log4j configuration.
• Log file locations.
• Database details and datasource configuration.
• IP addresses for external systems and Windows host entries.
• Subversion client configuration.
• Database population instructions.
• Java FAQs, tips and howtos.
• Links to vendor product documentation (e.g. PL/SQL references and application server docs).
• Application deployment instructions.
• System test release instructions and announcements.
• Performance test results.

Looking back, we captured some really useful information, some of which is reusable across other projects. Additionally, we've got a great knowledge base for follow-up work and/or new starters to the project. Although I was the only person contributing to the blog initially, after only a week or so the whole team bought into the idea, probably because my e-mail memos became "I've just put details of X on the blog". Incidentally, we had lots of the following conversations.

Team member A : How do I do XYZ?
Team member B : It's on the blog, just do a search for X.
Team member A : Got it, thanks!

Effectively, I think of our project blog as an agile way to capture documentation. Typically I've used wikis in the past, although there's something that I don't like about this and I can't quite put my finger on it. Sure, wikis are much better than blogs for organising and structuring information, but there's something about the immutability of a blog entry that appeals. While I wouldn't necessarily use a blog for recording formal project documentation, I think it's great for what we've used it for here. I'll certainly be running a project blog again and it will be interesting to see how this approach scales up to larger projects. Essential? No. Useful? Very.

Now that I've got some more time on my hands, if you're in London and would like us to come over and chat to you and your team about this kind of stuff in more detail, please feel free to drop me an e-mail (simon.brown at evolution.net) and we'll sort something out. Alternatively, just try it for yourself. Grab Pebble and you can be up and running in 5 minutes!

Responses[6]

Posted by Simon Brown on 07 April 2005 23:37:24 BST #