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.
Click here to learn more about the Business Analyst Template Toolkit
I too would love to know more about the documentation a Business Analyst would provide the team versus the Software Architect. Furthermore, how the two roles compliment each other or perhaps conflict?
I am wondering how many business analysts will actually challenge the existing corporate standards for documentation, even though those standards might be outdated and perhaps even essentially useless? How many business analysts skip the confrontation aspects of attempting to get standards for documentation altered and simply work around them? And, how many business analysts simply follow the standards without thinking?
Thanks Durga, Leslie, and Jarett, Thanks for all your input. I can see we have some very different practices here. This is interesting.
I have typically worked on projects with less in the way of formality and without a system architect role on every project. So the use case typically accompanied a broader system design document with the approach outlined for the project. Together these two documents provided the input the developers needed too begin to write code. I think I’ve also been working with fairly senior level developers and they are able to break down the functional requirements into system requirements and begin to write code. Typically I also deliver wireframes with use cases. So the requirements are fairly detailed, in terms of fields, logic, and business rules before they end up in the hands of the developers.
I’d be interested to hear more from other readers as well about the contents of the technical specs you hand off to the development team and how much of the detail you deliver vs. a solutions/systems architect you might be working with?
Laura
Hi Laura
Basically I go for separate documents considering the audience I am writing for. May be it’s because I have worked on projects where domain (functional knowledge) plays a vital part.
Basically usecase case will only tell “what to implement”, the functionality. These usecases can be embedded into the FRS. The end audience of a use case is the solution architect or system architect, QA team and not developers. You cannot expect dot net or java developer to understand functional terms.
Functional req after analysis is converted into prototypes, screen level description, a level which completely described “how to implement” the functionality. The end audiences here are the developers.
System documentation will include the details of finished system you won’t be adding the crude prototypes but will be adding the final screen shots of the finished systems. This document will tell user ‘what is implemented”. The end audiences here, as u have correctly mentioned are business analysts, project managers, and product owners.
I see 4 main purposes for use cases and their derivatives:
– the use case storyboard is the introduction to the user guide.
– the use case realization is the introduction to system design.
– the test case may be use cases with test data added.
– the use case itself, which is a means to identifying the requirements.
That’s a lot of re-use from a single artifact.
Leslie.
Thanks for the clarification Laura, yes usually have our ‘as-built’ documents such as the ones you described created or updated at the end of some period of time (usually a release).
Hi Jarrett,
As I’m using it in this post, “system documentation” is a set of documentation that describes the requirements met by the system. It is useful on an ongoing basis for business analysts, project managers, and product owners/managers who need to quickly understand how the system works today. It’s typically separate from a user guide. A user guide would typically incorporate the business process while system documentation would most often not reference the business process.
I like the idea of keeping user guides, production support and even system documentation updated as incremental changes are made. I think this works well in a maintenance environment. On a larger project, you might change things several times before you release the functionality and there can be value in saving the effort invested in system documentation until the end of the project when the requirements and system stabilize.
Laura
Hi Laura,
I’m curious as to what you consider ‘system documentation’. Who is the audience of this document? End customers? Production support developers?
If you’re referring to a user guide/manual type of documentation then I can see the value of the BA performing such a task, but if you’re talking about production support type documents I have my developers create that documentation. In either case, both are required as part of our definition of completion for any given user story and as such as both updated on an incremental basis rather than as a single activity after development is complete. I find this ensures the tasks are completed rather than suffer from ‘there’s no time’ syndrome.
Sometimes our user stories warrant little in terms of updating the user guide, but we usually tackle stories a theme at a time, or we break up an epic into smaller stories. Thus the BA will work on the user guide for a collection of stories when it is warranted.
Pingback: Tweets that mention Technical specifications and system documentation can take different forms -- Topsy.com