The Code Whisperer

I’m not a big fan of fast food restaurants such as McDonalds, but one thing they do very well is consistency. It doesn’t matter what country you are in, the restaurant has the same feel about it, albeit with possible a different language. The layout is very similar and the ordering process identical; if you have been in one restaurant you know exactly how it works.

However, this isn’t done just to make you feel good. Consistency is an important part in making a decision; if you know what to expect it can make a decision easier to make, particularly when it comes to food and trying to satisfy the catering needs of a young family. The other reason is speed. If you know what to do you waste less time, straight in, order, eat out. Fast food restaurants work on a high turnover of customers to make money, so everything they do to support this boosts the bottom line.

We spend several weekends and a week each year in the Dorset town of Swanage. Aside from the fact it’s a picturesque part of the country and only a couple of hours drive, the main reason we do this, and go to the same campsite every time is that we know where things are and how it works. We don’t waste time finding the supermarket or the best car park, we know that so it maximises the time we have away. We have a pot of 20p pieces for the shower, we don’t have to get change from the local shop. A weekend feels like a weekend, not a few hours in between trying to get the essential things done.

Back to software development. Let’s take a quick overview at the development lifecycle:

• Business requirements
• Technical design
• Coding
• Testing
• Bug fix
• Release
• Usage
• Support

Each of these steps requires some form of documentation and, with the possible exception of business requirements, will require reference to other documents in the lifecycle. It’s highly unlikely that one person would be responsible for each step in the lifecycle, and it’s possible that each step will be carried out by different people.

So what you don’t want is a free for all with document layout. The person looking into a bug discovered in testing wants to open up the documentation and know where to find the information they are looking for, not waste hours searching through documents.

I talked about managing programmers being like herding cats in an earlier post. This is also true with document layout. Each programmer or analyst will produce a different layout, based on their experiences of the past, which also changes over time compounding the problem. I’ve seen too much time wasted in the bug fix phase of a development looking for and through documents for information when the actual fix took minutes, or wasn’t a bug just a misunderstanding of the business requirements by the tester.

What can we do to improve the situation? Here’s my action plan for managing design documentation.

• Create templates for each type of document produced in the lifecycle. The documents must feel like the same family and as much as possible be laid out the same. Pay attention to the order of information in the document, this is key to locating details in a completed document. Use a font that’s easy to read on the screen and when printed - choosing a font that doesn’t display well on the screen will lead to more documents being printed, something you want to avoid for several reasons. Don’t forget to include copyright and distribution notices if they apply. Involve team members in the design, but have the final say. The templates will evolve over time - this is fine.
• The document template used is part of the document’s review - if it doesn’t use the correct template the document fails the review.
• Make sure the templates and the documents are easily accessible and searchable and that the design and development teams understand the importance of consistent documentation and know where to find templates and documents. There are a number of document management tools available, but sometimes a simple but well though out directory structure is sufficient. Make tools such as Agent Ransack available for searching. If it will make the location of documents easier create a document index, which can be a spreadsheet or another document.
• Consider version control software. Subversion is a good tool and using Tortoise SVN it integrates with Windows Explorer. Numerous Subversion hosting services exist, so as a bonus the documents are backed up away from the office.
• Recording bugs must be easy and the information provided comprehensive. Whatever system is used it must be possible to attach screen dumps, screen video and log files. Assuming the bug is found as part of a test plan, references to the test plan and the part of the business requirements being tested must be included. The developer correcting the bug must be able to add information about the fix applied as this may be useful in the future. I’ll cover bug tracking in more detail in a future post.
• Documents must be updated as the development progresses if they are to be of any use in the future. And don’t forget the future is just as far as the next step in the lifecycle.

If you are planning to outsource a project the quality of documentation is vital to the speed and success of the development. I’m in the process of putting together a Software Development Toolkit for small businesses that helps small businesses develop software, whether using a small in-house team or outsourcing. More on this later.