Where does documentation like business and software requirement spec docs fit in an agile project?

Question

We are implementing scrum in our company. The problem we faced is our traditional thinking, which always requires physical document.

Management is constantly asking for documents like Business Requirements Specification (BRS) and Software Requirements Specification(SRS).

When moving towards agile, is it ok writing user stories and their acceptance criteria as an alternative of (BRS and SRS) in a single document?

If that's the case, can you supply me with templates or examples? Is there something like an ISO standard related to Agile documentation?

We use TFS for project management.

Answer 1

In the manifesto for Agile software development one can read:

Working software over comprehensive documentation

This doesn't mean documentation is a bad thing. Instead, working code is better so you can document what you are going to code.

That being said, user stories and acceptance criteria might be all you need to understand the requirements, considering you're not responsible for the Vision and Scope Document.

Answer 2

I encourage people not to think of user stories (or backlog items of any kind) as another form of requirements. There is a critical difference in thinking between the use of requirements documents and backlogs that teams and organizations need to understand in order to effectively use the latter. Backlogs are emergent. This means that they not only change over time (there's nothing stopping a BRS from changing) but that later backlog items build on and modify earlier items such that it is possible that the earlier items no longer describe the application's behavior.

This means that the documentation you require will largely be separate from your requirements (think of it as what you walked into development knowing vs what you did in development). Note that things like ISO 9001 is mostly about validating that you follow your processes (whatever those happen to be) and that you record information you will need to audit or maintain the software later. The days where documentation and audit standards were about making sure the result matched the original idea perfectly are largely gone. The only place I see that anymore is places where they have it written into their processes and don't want to change the documented processes, in which case it's a conscious choice, not a constraint.

Adding this section to respond to the comment:

Agile and Scrum can be confusing to adopt because there are a lot of good practices that people have come up with that have been lumped into Agile and Scrum, while at the same time, many of the core practices and principles get left out.

Agile: Agile is just values statements and principles. You can find them at https://agilemanifesto.org/. You can't really practice Agile - rather, your practices can be more or less Agile (as an adjective) depending on how well aligned they are with these values and principles.

Scrum: You can follow Scrum practices. Scrum is a lightweight framework, meaning it gives a number of events, artifacts, roles, and practices, but there's a lot of space to fill in how you do the work and what that work looks like. You can find the latest version of the Scrum Guides at https://www.scrumguides.org/scrum-guide.html. It is probably worth noting that if many teams pick and choose what to follow out of Scrum. While that isn't inherently wrong, it is designed to work as a whole and many benefits are lost when you start dropping practices.

XP: You didn't mention this, but a lot of practices common in Scrum that aren't specifically listed in the Scrum Guide (like User Stories) are actually from XP. XP is a lot more prescriptive on how to do the work. There's a pretty big change curve with adopting XP and I don't see many teams do it, but when Scrum started, they were often assuming that XP was going to fill some of the how-to space in their framework, so it's always worth looking at. http://www.extremeprogramming.org/ is a good place to start, if a bit clunky.

Answer 3

Customer-side BA here, currently in the middle of a large-scale enterprise data warehousing and infrastructure modernization initiative. The project teams use Jira instead of TFS, and though the concepts are the same, our use of the platform is mainly as a tracking and reporting tool to interface with the core (enterprise) Agile development team. The focus of our user stories are mainly to discuss and track testing, enhancement requirements, defect reporting - all of the type of feedback that comes "after the fact" of each sprint's work-product, so to speak, and well after the initial requirements have been published.

Key commentary on the BRS/SRS specifications - these should be solicited from end-users in the planning/prototyping phase in order to prioritize architecture development and to develop the overall project plan; this can be accomplished with a survey or other requisition assessment tool, drafted by technical leads and the E/PMO and sent out to consumer leads in the initial stages of planning. This allows the E/PMO to gauge the baseline scope and feasibility of the draft requirements, make necessary resource allocations, and prioritize work to waves, sprints, along a kanban board, etc. for the methodologies in play.

User stories, on the other hand, tend to be more focused on responding to feedback over particular channels, services, domains, or templates that arise after consumers have conducted feasibility and gaps analysis against the prototyped release.

In short - while the exact purpose of each document will vary across different organizations and projects, the requirements documentation and user stores are ultimately apples-to-oranges, however all three could feasibly be combined in the same basket of fruit. Emphasis on the role of each should be tailored to the interests of the group(s) driving the initiative.

End-users will set their requirements ahead of time and independently of the work being done in each sprint; they will likewise continuously adjust their plan in alignment with BA/DevOps feedback along the way - this communication gets relayed through the user stories during development as a tracking bulletin of sorts. The three are complimentary, but oftentimes they'll serve to document the interests and needs or distinctly different shareholder groups.

Answer 4

Documentation as code

is the key phrase here.
Modern testing frameworks combine english readable content with the instructions to perform the actual testing, system calls, UI interactions, etc.

Under BDD (Behavior Driven Development), as with TDD you specify the behavior up front as a test, e.g.

The users enter AB234, presses return and sees her access code

The test fails of course as no actual code has being written yet to implement it.

You then write the code and the test passes and then, critically, you have one more test in your suite for the future (often termed regression but I avoid that term, it's just the test suite, same as all testing). You can now run this test to assure functionality works and often include a flag or setting to show the human readable part of the tests that passed or failed.

Answer 5

Agile approach ≠ lack of documentation

If you need to document really important things, such as resources, working hours, equipment required, of course, you can do it. I’d rather say, you should do it.

Using the agile approach you may create only summary documents that picture the ongoing situation.

An interesting fact is that in the traditional approach there is a lot of comprehensive documentation which actually is not essential and valuable.