Documenting agile projects
If you’re in an agile team with a healthy backlog, you know what you should be working on next. You have well written stories with acceptance criteria, why would you need anything else? Just pick the first story and get going.
It’s good to question everything, but it may be helpful to have documents. Don’t believe me? Let’s take a look.
Why document?
The role of documentation is always to share an understanding of something. When we did it back in the waterfall days, it aimed to paint the picture of the final software.
The waterfall documentation is long and complicated, and rarely revisited after the project starts. It consists of long, detailed documents that lose meaning over time.
In the Agile days, we have a backlog that does half the job: Giving an overview of what is going to be delivered. It is enough to give people a sense of where things are going, but it alone is not always enough.
Documentation can help everyone be on the same page, and avoid misinterpretation or confusion. Having just a few documents that enhance understanding, and are fast to make, is the way to go.
Enough is enough
The rule of thumb is: Make only what’s essential, not a hairline more. Documenting in the old days was just a thing we had to do, without much thought. We didn’t question whether to do, and what to do, it was part of the process.
You should document an agile project to the point where you reach full understanding. Stop when everyone knows roughly how it’s going to work. If scribbling on a napkin is what gets you there, that’s your documentation.
After a couple years working with agile projects, I’ve found a formula that works most of the time. An App Flow plus a Lo-fi Wireframe can help a team understand a product in minutes.
App Flow
The App Flow is a diagram that, as the name says, show how the stories flow through an app. It helps understand the big picture and how everything is connected.
Having such a document is good to explain the project to new people, like sponsors. It is also helpful when you need to revisit something or answer a question. Most of what is going to be delivered is in this diagram.
To build an App Flow you need to figure out what are the steps your users will go through to do solver their problems. Then you need to describe those steps and show how they are connected. Doing that for the stories on your backlog gives you an App Flow.
You can download the App Flow template and start creating your own right now.
Lo-fi Wireframe
Using a low fidelity wireframe is the quickest way to let someone interact with your product. It takes a small amount of time and get something in front of the user or client.
It can be built using the tool you have at hand, from pen and paper to digital tools like Balsamiq. I usually go for Balsamiq because it lets me generate clickable wireframes and share files. That makes it easy to share and store this document.
But I often find myself documenting small, side projects with pen and paper, and it works as well as digital. The Lo-fi wireframe type depends on who are you working with and how much you need to share and test it.
You shouldn’t be doing high fidelity mockups as documentation, since they are hard to create. You would need to invest too much time, and it would get harder and harder to change anything. The Lo-fi wireframe does the job most of the time.
Is that enough?
That only you — and your team — can answer. Often it’s been all me and my team need, and it’s helped us communicate better. You may need to find some other techniques to incorporate in your workflow, and that’s fine.
Each business is different, and hence needs different solutions. The only thing you should make sure is that you’re not making anything useless. If you can take away a document and people still understand the product, you’re doing too much.
This article is part of a series that help you tear down the walls in your organisation. You can take a look at:
