It is human nature to want to excel at our chosen profession.
When given the opportunity, many of us are tempted to show our expertise by listing everything we know on a single piece of paper. Therefore, when we are asked to draw a picture of a system and its interactions, we will put on it what we know. For real life examples, check out the first few minutes of Simon Brown’s talk about Visualising Software Architecture.
When it comes to building a good solution to our perceived problem space – we don’t always want to know the details, at least not to begin with. What we want to answer is the following question:
“What is the problem I’m trying to solve?”
Before you can answer that question, you need to ask another:
“What is the situation we currently find ourselves in? i.e. what is the problem space?”
And before you can answer that, you require a context. A context is nothing more than a map showing where you are. A context diagram of our systems shows us where we are in our systems journey – what systems talk to which other and where people get involved.
When we can name all of the systems and the people involved, we have built our context diagram. We have built our map.
Therefore the steps to writing great requirements are always as follows:
- Start with a shared understanding of the systems context and the people who are using them. A C4 System Context diagram can help here or just a top-level sketch with people and systems represeneted.
- Use the diagram to explain the changes that you want to happen for the people who are using the system. Use the diagram interactively to challenge assumptions.
- As you progress, discuss and present options for any changes required.
- Once a choice is made, write requirements that get your diagram from the current picture (as-is) to the new situation (to-be).
- Now you can start iterating into your diagram to see what details may cause problems. If you’re using C4 then you can start to fill in containers, components and even code if you feel you need them.
- When you are satisfied that you’ve adequately represented your context and containers and details beyond that, you’re in a great position to write accurate requirements that describe your change.