How to document requirements and not put people to sleep

A project requirement document whether functional or technical is a snooze fest for any techie to read through. The start of a project is the most important phase. Well thought through requirements play a large role in the project's success. But this probably remains, the most critical yet boring phase of a software development cycle.

On the other hand, imagine the requirement writers state of mind. Someone who has painstakingly tried to document every scenario that they could possibly imagine. Knowing fully well, there is a good chance something is going to get missed when the implementation hits the road.

Throw in some other challenges:

You are dealing with developments teams spread across geographies. Places where English is not their first language. A lot could get lost in translation in such scenarios, through no fault of anyone.

You have a set of requirement documents which have captured everything needed on day 1. How do you keep this current when changes start coming in thick and fast?

You would like your development teams to have a holistic view of the project even though their focus areas are limited to a set of components from the entire project.

Personally, I have come to believe that using a Mind Map to capture a systems requirements is the best way to alleviate these challenges.

Read someones mind or open your mind to someone

Check out this mind map describing Tennis to a novice Courtesy wikipedia

This map covers the type of shots in the game, scoring mechanism, playing surfaces, key tournaments and key principles. Along with this it covers trivia like the fastest serve and other bits of information. Enough to upgrade someone from a novice to an amateur level understanding of the sport.

The same level of information if covered in a document would be verbose and could loose a high percentage of readers mid-way. Writing information in form of a mind map increases the chances of your readers going through everything you have documented. Moreover, this format also increases the chances of the concept being understood.

Here's how you can start using it for your project.

1. To start mind mapping, try FreeMind it's free and makes it simple to create and distribute map files.
2. After you have downloaded and installed FreeMind try documenting a project or module you are working on.
3. Put the name of your project or the module you are documenting in the first (root) node. From the Format menu option click on Automatic layout. This will ensure your map looks pretty right from the outset. You can edit these layout options as you go along.
4. Identify your key stake holders and put that as your first set of nodes after your root node. For example for a ticketing system Customer & Customer service team could be the the first set of nodes.
5. Next up, identify the key use cases for each of these stakeholders. For ex. A customer would need ability to raise a ticket and check status of their tickets. You can add subsequent nodes to these nodes and detail out the fields and rules associated with the node you are working on.
6. If you need to add an explanation or a note to a particular node, click on the node and navigate to the View menu option and click Note Window.

The beauty here is each node comes with a context as it lies in a certain position within the hierarchy. If while reading your user loses context, they just need to back up within the hierarchy to find context. Making mind maps easy to walk through while explaining a concept or project functionality.

Detailed mind maps can be quite large and can cover every aspect of your project in detail. If you haven't it tried before, its certainly worth a shot. Here are some more usages of mind maps. Check it out.

Comments

[Kim Arnett ]

Do you think the same could work in preventing yourself to fall asleep while writing? :)

[Shuhaid Lambe]

From my own experience of writing both documents and mind maps I would say yes it would delay if not prevent you from sleeping :)

[Rafal Pienkowski]

Very nice article. Such a mind map could be useful to imagine how the solution would look like.
Do you have any experience to work with mind maps with customers ex. by sprint planing in agile methodology? What is their filling about that idea?
On the other hand do you have to convince other developers to work with mind maps?
Do you use mind maps to draw only a big picture of a project or do you use it to describe details?
Sorry for huge amount of questions but the concept is very interesting and I'm considering to use it in the future.

[Shuhaid Lambe]

Hi Rafal, Thanks for the comment :) I will try and answer these queries by breaking it down.

1. Sprint planning & customers feedback on usage of mind maps
Mind maps can facilitate sprint planning, as it allows you to focus on a particular section or module of your project and everything that is required to complete it. And visually shows you where this module fits in the full picture.

Customers love seeing their project in this form. As it gives them a visual representation of the solution. It has also helped us to ratify a solution with multiple customers & stakeholders quickly over a meeting or a phone call.

2. Do you have to convince other developers to work with mind maps?
I have found developers liking the idea of using something more visual rather than writing documents. Having said that though, some folks need more convincing than others. Just like how adoption of anything new takes time and effort, this is not going to be any different.

Do you use mind maps to draw only a big picture of a project or do you use it to describe details?
Both, it depends on the nature of your organization and project stakeholders. If they are receptive to the idea of using mind maps then there is no reason why i cannot be used across the board.

[Rafal Pienkowski]

Thank you for detailed answers. Once again very nice article :)

[ImTheDeveloper]

Fully agree. I have found the use ofa mind map to help elicit requirements gives great coverage. You might want to take a look at Microsoft's vosual models for software requirements book. It discusses the feature tree which is another good way of modelling requirements

[Shuhaid Lambe]

Thanks for the feedback will check it out :)