David Develops (Software)

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.

I hate meetings but I love stand up meetings- contradiction?  No.

They’re a brilliant, informative, low impact way to keep communication fluid amongst your (small to medium sized) team, regardless of profession.

I’m going to talk a little about the reasons I’m writing about this, before getting on to the anatomy of my perfect stand up meeting, then tell you what stand up meetings could do for you and your team.

The Media Circus

My partner works in magazine journalism as the chief sub-editor for a title with a reasonably large international circulation.  Consequently, every month without fail, press week is a nightmare.

As is apparently the norm in the publishing industry (or what’s left of it) the eternal cycle of content creation is a very stressful process.  Freelancers are always late; things never hit the editors desk on time, people have to be continously chased up, facts need to be checked, and all before a press date.  If this isn’t complete by the press date, the company starts haemorrhaging money by the hour as the presses are literally “stopped”.

All of the above is exaggerated by the fact that writing is one of the industries that allows single workers to effectively “go dark”, drop off the radar and appear x-days later with finished content.  Not exactly communicative, ironically.

You Were At Work How Long?

She’s quite durable in regards to getting work done and quite effective at not letting the battle of press week become emotional or stressful, but I get the distinct impression it can be highly frustrating when you’re working until 11.30pm and getting the last tube home for a few days at the end of every month just to cover for the lack of structure to publishing a medium sized monthly title.

This pattern cumulated in a conversation with the good lady, with her expressing a little bit of exasperation on the topic and wondering if there was actually anything she could do to ever change this bad pattern of behaviour and improve the workflow of the entire team.  To me, there were a few simple tricks that could be employed to help facilitate change.

The Programmers Perspective

As a stark contrast I work in technology, specifically software development using what commonly comes under the banner of “Agile Methods” (there’s an on-going debate as to what counts as an agile method, but that’s beyond the scope of this piece, and frankly, my patience).

I’ve been lucky enough to only suffer one professional role that insisted on following an old trusty waterfall model of software development- that is to say, a software project where you first sit down and collate a monolithic requirements document, then produce a complete system design, then implement it, then deliver it.  Because of this, I’ve been working “agile” since my second professional role, and the first thing I was introduced to on my first day was the concept of the “Stand Up” (meeting).

I’d never come across one before, but they turned into one of the most useful parts of my day, and for something that lasts the best part of 10 minutes, that’s saying something.

What’s A Stand Up?

To quote the Wikipedia entry in it’s entirety:

“A stand-up meeting (or simply stand-up) is a daily team meeting held to provide a status update to the team members. The ’semi-real-time’ status allows participants to know about potential challenges as well as coordinate efforts to resolve difficult and/or time-consuming issues. It has particular value in agile software development processes, such as Scrum, but can be utilized in any development methodology.

The meetings are usually time boxed to 5-15 minutes and are held standing up to remind people to keep the meeting short and to the point. Most people usually refer to this meeting as just the stand-up, although it is sometimes also referred to as the morning roll call or the daily scrum.

The meeting is usually held at the same time and place every working day. All team members are expected to attend, but the meetings are not postponed if some of the team members are not present. One of the crucial features is that the meeting is intended to be a status update to other team members and not a status update to the management or other stakeholders. Team members take turns speaking, sometimes passing along a token to indicate the current person allowed to speak. Each member talks about his progress since the last stand-up, the anticipated work until the next stand-up and any impediments they foresee.

Team members may sometimes ask for short clarifications but the stand-up does not usually consist of full fledged discussions.”

You’ll notice that there’s a hell of a lot of references to software development both in the prose and on the Wikipedia page and it surprised me to discover that outside of technology, stand ups aren’t a common thing, they essentially don’t exist.

I could hardly believe it at first, but a cursory Google search for “stand up meeting” concluded that outside of software, stand ups either don’t exist or are so rare as to not appear on general business websites.

For the sake of completeness, it’s worth noting that the internet is always skewed to technological topics in these kind of searches, but when all the results are about programming I can at least see some anecdotal evidence to confirm my suspicions.

My Favourite Stand Up Meeting Pattern, And What It Gets You

First things first, I really don’t like calling “stand ups” “stand up meetings”.  I always feel like the word meeting is loaded with negative and tedious connotations- meetings are boring and shitty and people don’t like going to them, period.

It’s important to note that because a stand up isn’t really a meeting, it doesn’t have the emotional baggage associated with one.  A stand up works best for teams of about 2-15 people (for the sake of brevity).

The Ideal Stand Up

A perfect stand up lasts between about 10 and 15 minutes (you’re “standing up” to try and enforce this) and takes place EVERY day.

The jist is, somebody starts it off (it doesn’t matter who) and everybody states what they did yesterday, what they’re planning on doing today, and anything that they think is going to get in the way of their current task.

Other team members are allowed and encouraged to comment and ask brief questions after the current speaker has finished.

The meeting should take place roughly 20 minutes after the start of the working day, to allow people time to sit down, get a coffee, have a chat, read their email and work out what they’re doing.

What You Get

The idea is, through the use of this simple 1 to 2 minute exchange from each person, everyone has a much clearer understanding of what each team member does.  Just ask yourself, do you REALLY know what all the members of your team do?  This is especially pertinent if your job involves managing your colleagues in some way.

The other participants should be encouraged to ask questions and comment after the speaker has finished but in-line with the comments they just made.  The idea behind this is that another team member may well have solved a problem that the speaker was suffering, but due to isolation, the pace of the workday or a lack of communication the fact that the problem has been solved may have been lost.

It’s a great way to share knowledge and has a very low impact on time.  The one caveat is that any lengthy discussions should be followed up privately after the stand up, because if you stray into detail or go off on a conversational tangent you’re wasting collective group time.

Psychological Effects

Stand ups make your team work harder and more efficiently.

That sounds absurd but stay with me.

Because, of the permanent rolling accountability of stating what you’ve been up to, stand ups are a good way of reducing the likelihood of your staff time wasting.  They’re nice and self regulating, nobody wants to stand in front of their team and say exactly the same thing, every day for a week.  It attracts the kind of attention that most people, lazy or not, prefer to avoid.

Past that, people enjoy having something new to say every day.  It’s a little like a grown up, caring sharing version of show and tell for the business world.  You don’t want to be the kid that doesn’t participate.  Peer pressure?  Totally.  But it’ll make your team more effective.

This side effect has two key uses.  Firstly, it positively encourages teams to be proactive, but secondly, it gives the managing member a very solid handle on team activities (or if relevant, the lack of).

Will This Work For Me?

Honestly?  I don’t know.  My experience is very slanted towards technology businesses so please remember your mileage may vary.

I think stand ups are a vital and useful part of an agile team however you shape them, and I’d say it’ll certainly work for you in software development.

Outside of technology, I genuinely don’t see how these clearly transferable practices wouldn’t apply and give you at the very least, team communication benefits.  Even if you think your team communicates well, ask yourself how much you know about both your colleagues’ roles, and what they’re doing today.

I found a good article on the anti-patterns of stand up meetings; the stuff to avoid.  I’d recommend having a quick read of it, in order to have all the information.

If you think the answer could be “not enough” than I’d really recommend you give it a go.  I have no idea if the good lady is going to suggest her team experiment with stand ups to help smooth out the pressures of their press week, but I think it would be an awesome idea for everyone.

I love stand up meetings and you should too!