Writing stories in cards is not enough / part 1

Software projects fail for a number of countless factors. One of these is that requirements are incorrectly captured, not fully expressed, shared and understood by all actors involved in the project.

In this post, we review an ideal set of best practices to manage your requirements, expand them in user stories and make sure that every member of your team fully understands them.

Requirements are usually captured in work sessions where all project participants (or in less fortunate cases only key figures) gather in a meeting room with a large whiteboard, a few chairs and countless post-its.

From such meetings, you can generally expect a positive outcome: the overall requirements are first discussed and then dissected. Most likely, after a few hours, everyone leaving the room feels like the meeting was great and everyone is convinced just had a great start, paving the road to success.

The truth is that this meeting is simply the first step of a long series which, most often than not, will not end as expected. Let's see why.

Problem #1 is that, following the meeting, all requirements get transcribed in some long document that no one will really read carefully. The document will be too long and too bureaucratic. It will be plagued by version numbers, indexes and blank, unused spaces. Even worse, it won’t have pictures in it, it won’t be visual enough!

Often the definition of the requirement is in fact tasked to the project owner that being a managerial role may not have the graphics skills to represent an effective synthesis of the solution in a few key images. Most likely a wireframe will also lack.

The project owner therefore issues a super-verbose document where the requirement becomes a classy topic that no one will really read carefully. Or rather, if business users may also have the maturity to do so, the weak link reveals itself to the development team that somehow looks superficial to the written requirements, interprets them quickly, and puts the code on the job.

Problem #2 is that project owners rarely consider the opportunity to collect feedback from project actors in a proactive way, often relying on silence-consent: me the project owner I have sent you a beefy requirements document and since I cannot baby-sit you for you comments, if you do not send me a response within a number of days, I will just consider that the formulation of the requirement is accepted. And that's a big mistake.

Requirements, once transcribed, should be presented in a highly visual document, with images and diagrams and approval from all team members should be actively seek'd out.

The trick to effectively invite people to read your documents and provide feedback is to forget conventional approaches and write your specifications like you were writing a software manual. To do this you can use Herogami's wiki, we'll see that soon in part 2 of this long post.

James Albertson, Customer Support

16 Jul 2017