Why the big picture is important and how to keep it

Summary

Effective software development requires a clear big picture to guide the project and maintain focus amidst changing requirements.

Abstract

The importance of maintaining a big picture perspective in software development is crucial, as it helps to transform a list of requirements into a coherent vision. Despite the initial magic of conceptualizing functioning software, developers often face challenges as requirements evolve, leading to an ever-growing list of demands. To combat this, it's essential to start with a high-level overview that captures the main functionalities, user roles, and interface descriptions. This big picture serves as a map for stakeholders, providing a shared understanding and a reference point for the development journey. It should be concise, understandable, and continuously updated to reflect changes without becoming a cumbersome burden. The big picture document is not a detailed specification but a guide that facilitates communication and alignment, ensuring that the project remains adaptable to necessary shifts in direction.

Opinions

The author emphasizes the transformative moment when requirements evolve into a tangible software concept, likening it to a magical experience.
A common mistake is to dive into detailed documentation without first establishing a shared vision, which can lead to overwhelming and ignored documentation.
A successful big picture includes a contextual summary, main functionalities, high-level interface descriptions, process models, and a simple graph of main screens and components.
The big picture is not a contract but a living guide that should not hinder adaptability, as per the Agile Manifesto.
Keeping the big picture document concise and up-to-date is vital for it to remain useful throughout the project lifecycle.
The document serves as a mental model snapshot, aiding stakeholders in maintaining focus and understanding without overloading their working memory.
Visualizing and documenting the big picture helps the author to better grasp the project and explore unconsidered issues and ideas.

Why the big picture is important and how to keep it

There are many great tools, techniques and methodologies to collect requirements. You can use plain sentences, use cases, user stories or whatever what makes sense to you. One way or an other you will end up with a nice list in your pocket, where everything makes perfect sense, there are no gaps of contradictions of any kind. The first moment when my requirements start to transform from a set of sentences into the concept of a functioning software is magical. I hear the song of the angels, unicorns are dancing on rainbows and I feel fulfilled that I achieved something great in my life.

Then comes the horror. The customers keep coming up with new stuff, they change their mind, the developers complain and the nice and beautiful list is just keep growing and growing.

Start with the big picture

When I got my first project I did a few capital mistakes. I participated in some kickoff meetings and workshops and I had a vision on my mind. I worked together with a UX guy, who also had more or less the same understanding as me, and he sketched up an initial concept in inVision. I thought that this is cool enough, so I did not bother to work on it, instead I mindlessly started to create all the epics, user stories and acceptance criteria. I ended up with a 250 pages documentation as a “draft”, I still have it somewhere in a box to use it as a memento of my heavy past. So I gave this documentation to everybody, and however everything was crystal clear to me, I noticed how people got a meltdown and stopped reading it. They got tired, they got lost, they gave up. Having good stories and having a backlog is not enough. People need to see a big picture, a backbone, a map to know where to begin and where to go.

Cover the most important aspects

I like to start with a short description about the context of the software, what is the problem to be solved and who the users are. I like to continue with a summary of the main functionalities and refer to the requirements by ID. The summary must be in clear understandable human language so even a manager’s mother can understand it. Then I find it important to have a high-level interface description, because if you depend on other systems and you have absolutely no idea at the beginning how to communicate them, what you expect to send and receive, you will be in a big trouble later. As a next step I pick the requirement list and I define high-level processes based on them, and I refer to the requirements by ID so it is clear why something in the processes is necessary. This process model does not substitute proper specification, it’s only supposed to make major flaws in the concept visible and to help having a common understanding between the stakeholders. Last but not least I like to make a very simple graph about the main screens and components. No wireframes, no design, just plain boxes with names, so the reader can have an idea about what can be expected. Keep in mind that you are not writing a specification, you are making some sort of an elevator pitch, which must be short and clear for anyone who reads it, not just for IT professionals.

Don’t stick to IT

As I mentioned before, the big picture is just a map which helps people to gain a basic, common understanding , to help them orientate themselves. It does not replace any documentation and specification of any form and it’s not sufficient to develop anything directly based on it. As the Agile Manifesto says, this is not a contract and not an agreement. It’s a guide. Don’t stick to it. If something needs to be changed or detailed, you can’t use “but we agreed on it in the big picture document”. No you did not, you agreed on the requirements, and the requirements in agile change.

Keep it up to date

In agile the requirements keep changing, so you don’t want to have too much documentation, because then you need to keep them updated. If you made the big picture compact enough, then updating it should not be a major effort. Sometimes I find it boring and I think that once the project has kicked off and the development has ramped up, nobody will read it anyway. Then someone joins the project and the big picture is the first document they read through as an introduction.

A document like this is not just helping the stakeholders to have a basic, common understanding but it also helps you to stay focused. You just can’t keep hundreds of requirements in your mental model. When your brain reaches the limits of its capacity, it will start to erase things from your working memory and the whole concept will fall apart. It’s better to have a snapshot of your mental model somewhere with descriptions and drawings, so you don’t need to keep everything in your head and you can catch things up easily when you get lost. Last but not least writing down and visualizing what’s on your mind helps you to understand the topic better and elaborate on issues, cases, ideas you didn’t consider before.

If you enjoyed reading this article, please support me with a few claps. Thank you!