Do you demand that your documentation serve double duty as a technical specification and a system document? While in the past I’ve done exactly that, my recent forays into more agile practices forced me to split how I see the value in various pieces of documentation.
Adriana has already shared her views on how BAs help improve the quality of documentation on agile teams. I definitely concur! And today, I’d like to expand on that view by separating out the ideas of technical specs and system documents.
My Old Way of Doing Things
One beautiful thing about use cases is that they can play triple-duty. They are a decent tool as a technical specification. A developer can take a use case and begin to design and build code to support the functional requirements in the use case. They also often double as system documentation, which means that after all the code is written, the use cases are usable requirements documents in understanding the requirements of the system. Use cases are also a wonderful analysis tool in that they encourage you along your way of doing the hard thinking about how a system works.
As I became immersed in agile practices, I began to realize that placing these three different needs onto every document I produced created unnecessary headaches. I sometimes stalled as I took time to “figure it all out”. If your documentation is going to help the team deliver AND be useful long-term, you need to know a lot more about the product you are building before you write it.
Similarly, I fought requests to change or refactor documentation, which I now see as a sometimes necessary part of the business analysis process. An update to one use case often means a bunch of related updates to other use cases. When you are on a quest for perfect system documentation, you can feel a lot like a juggler during the delivery cycle.
The Goal of Technical Specs
Agile practices, especially the focus on ensuring documentation is relevant to building working software, helped me see that there is a lot of value in customizing how you present the requirements specifically for the development team. When working with an agile team, the user stories organized in a product backlog are the main communication points about requirements. I break up and rewrite user stories all the time to suit the needs of planning and prioritization. I aim to compartamentalize the requirements into small chunks of valuable functionality that can be built by the team in 1-3 days. This means that as I learn about the system and what it takes to build a specific feature, I update the backlog of stories. This requirements approach allows me to cater specifically to developers and help them be more effective.
Because use cases are such a wonderful analysis tool (just one of the many reasons I love them), I’ll often do some early use cases before I start defining my user stories. It helps me keep the big picture in mind and can be a useful tool to review with stakeholders and developers to understand the requirements and the concept. But I typically don’t use them as part of my technical specifications in an agile project.
The Way of the System Documentation
I still believe you need system documentation because it provides lasting value. I actually think that a documented system is more valuable than an undocumented system. Don’t you? Tracing through a large collection of user stories that build on top of another is an inefficient way of finding the answer to “how does the system work?”. And six months from now after you’ve left this project in the dust someone is going to ask you just that.
Thankfully, I’ve found that writing use cases after the system is built is a fairly low-bandwidth activity. Once you’ve built a product, retrospectively writing the use cases and capturing key decisions can typically be done in a small fraction of the time you spent on the product originally. For example, for a six month project I spent just a few days creating and updating system documentation.
The Pros and the Cons
I will admit, handling system documentation and technical specs separately does take more bandwidth from the business analyst on the project. In my experience, most of this bandwidth is consumed in reconfiguring the technical specs (or user stories) as you learn about the system and the delivery cycle.
But I think the reality is that if I wasn’t doing this in my more traditionally managed project, then someone else was. This probably fell to the tech lead or the project manager. And in the process, I’m sure some of the requirements were missed and we delivered less value than we could have. The business analyst can bring a lot of value to this reconfiguration because you can keep the whole system held together and ensure that each story continues to focus on value to whoever will use the system. You are not just splitting stories apart into pieces of code. You are splitting features apart into incrementally delivered requirements.
The other positive that comes from this additional effort is that I have a better tool to validate requirements with the technical team. In the past, this work typically ended with a use case review and a formal nod indicating “yes, we can do that.” And then I had to wait until the code was delivered to see if that was true. As part of being involved in planning and reconfiguring stories, I get a much better idea if the developers can make sense of the requirements and how they intend to build them. With improved requirements validation, I end up with better requirements in the end.
Looking to Improve Your Documentation?
Check out the Business Analyst Template Toolkit – my repository of go-to templates for streamlining communication amongst the business and software development teams.