I Know It Sucks, But You Need Requirements To Work

There are two parts of software development that really suck. Traditional requirements analysis and documentation. This isn't some silly joke, both practices are terribly antiquated and essentially useless, not least in an agile (read: rapidly changing) project.

However, one of the common misconceptions I often hear when working on agile projects is stakeholders not quite “getting it” and thinking that agile is the same thing as requirement-less development.

However you paint it, you need something that resembles requirements to write code with. Requirements needn’t be exhaustive, and in an agile environment are rarely ever final, but you need to know what you’re working on- the average user story isn’t going to cut it.  User stories are designed to start conversation between the developer and the stakeholder but you need to do something with the detail once you have it.

Make The Requirements As Accountable As You Are

You know what else sucks? The fact that most businesses don't have any kind of document management strategy. Sure, you do, you're a developer. You have source control (and if you don't, go take care of that now), you're accountable and auditable line by line, check-in by check-in. This same rigor rarely extends to other areas of businesses (though it should).

When all is said and done, if you’re maintaining a traditional requirements document for your project you’re probably already making a big mistake. Who owns the document? How do you track changes? How do you know people haven’t changed the requirements without a reasonable discussion? What happens when somebody accidentally deletes it?

Requirements documents are the “Excel Applications” of development. They’re unreliable, often so large that nobody will ever read them, and as such fundamentally useless. It’s a bit of a trick question really, monolithic requirements documents are about as “Write-Once-Read-Never” as most Perl code.

I Think We Have a Problem...

So lets recap. Requirements documents are evil and nobody reads them, but you need requirements to develop. Requirements documents aren't auditable yet it'd really be a good idea if they were. Oh and documentation sucks.

You Need Wikimentation!

Wikimentation is a particularly amusing portmanteau but what you need is a wiki and if you do it right, you'll never have to write documentation again.

In an agile project, the requirements are meant to evolve and change as you go, so they deserve to be stored in a format that naturally leans towards allowing the users to do just that.

There’s also an immediate bonus to either you or your business analysts in the way requirements are captured as a traditional requirements capturing exercise is eschewed in favour of documenting requirements as they become relevant. This is a very natural way of working and allows you to prototype or stub out components until you need to delve into detail (in fact, doing this is very much the SCRUM way).

When I approach a new project I like to keep a few things in mind, I’ll call them the Holy Trinity of software maintainability…

The Holy Trinity Of Software Maintainability

• Readable Code
• Good Developer Documentation
• Source Control

So how will a wiki help you get there? I'd argue that after the implementation of a set of requirements, the requirement and it's details have effectively been superseded by the precedent set in the code.

Those requirements you coded to, after implementation are useless. If the code doesn’t adhere to the requirement the code is buggy, and your bug tracking system should contain information explaining why.

If the code is correct, the requirements would be classified as obsolete. Keeping them around only serves the purpose of misleading anyone who attempts to read the requirements to establish the coded behaviour of an application.

So what we do is we maintain the list of requirements in a wiki in a slightly less formal manner. This is hypertext remember, big long lists of stuff are so 1990. Use links and divide the content into requirements for logical components, leaving a well maintained index on the project homepage in the wiki.

Now as features are completed instead of the requirements eventually rotting away into irrelevance, they can be replaced by a simple developer commentary of the implementation. As you follow this pattern, your requirements will develop into a solid set of searchable developer documentation at the same rate as your project progresses.

Constructing Your Own Evolving Requirements Wiki

There are plenty of FOSS and OSS Wiki platforms out there. I have a personal preference for ScrewTurn Wiki on Windows and you can be up and running in literally under 5 minutes (web server not even required).

A few simple guidelines

• Ensure that the home page of your wiki clearly links to the discrete sub projects or components you're developing
• It's encouraged to create wiki links for content that doesn't exist but needs elaborating on by yourself or your team, to serve as a visual reminder of what is left to do
• Create a standard template for a project and component wiki page
• Populate each of your component wiki pages with the top level requirements for that component, along with "pre-links" to any sub-components of specific note or percieved complexity
• Encourage your developers to document as they write
• Don't duplicate code comments or huge chunks of code in the wiki - that's what clean and readable code is for
• Do encourage the posting of examples for reusable or common components - share individual developer knowledge

The wonderful thing about using a wiki is that it breeds accountability. Modifications are logged and audited; you can always see the history of any given page, from requirements to documentation.

A wiki will provide you with a sound and adaptable framework for producing project documentation that evolves with your project. Used in conjunction with a good bug tracking system, a good version control system and some good developers, you’ll have a good chance at edging closer to that holy grail of maintainable well documented code at low cost.

Zero Friction Documentation

Your developers won't resent a little bit of writing as they finish off logical units of work, and it could be even encourage to keep a "scratchpad" of information on the wiki as opposed to paper-notebooks. It's also good to remember that you can always generate a traditional requirements document from the content stored in the wiki if an occasion calls for it.

I’ve had a lot of success implementing these ideas in past projects (both agile and none agile) and I’d certainly recommend it.