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.

  • 5
    If your company has an existing workflow that uses BRS and SRS then you should find out how those documents are used. What purposes are they serving? Who reads them and what do they do with them? Talk to the consumers of these documents about what they would need and if they feel your user stories would satisfy these needs. – Pace Feb 24 '19 at 18:02
  • Good i will,based on your experience, as a development team, can we implement the code based on user story bounded with acceptance criteria.In our current model the SRS feed into development team and testing team use the same document to verify the developed feature – Mjd Kassem Feb 24 '19 at 18:30
  • 1
    If the test team is deeply integrated in the development and participates in the creation of the story and acceptance criteria this can work. If the test team is external to the development team I think this would be trickier. – Pace Feb 25 '19 at 3:15
  • 1
    If you can manage to get every single relevant person related to the project implementation (stakeholders, technical leads, testers, end users, etc etc) in one room long enough to get all requirements written down as stories, then yes you can just use those as your requirements. (Sutherland's original Scrum book has a real example of this happening. But these days I'd say it's rare to be able to do that). Otherwise, unfortunately you probably do need some kind of BRS/SRS and you let the BRS be the "source material" for stories, with the SRS as a technical guide for the implementation team – Stephen Byrne Feb 25 '19 at 14:57
  • good, we are going to implement Agile as scrum,we will try to gathering the requirements as user stories with their acceptance criteria, we all as a team believed in Agile added values, we agreed that user stories will be as a single source of truth for all participaters, we hope to success and sense the Agile powerfullity – Mjd Kassem Feb 25 '19 at 15:45

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.

| improve this answer | |
  • 12
    A lot of people forget that the Manifesto lists eight important values, not four. The Manifesto makes a relative value judgement that the values on the left are more important than the values on the right, but it does not say that the values on the right are not important. The Manifesto explicitly says: "there is value in the items on the right". +1 for pointing that out! – Jörg W Mittag Feb 24 '19 at 22:27
  • 2
    really, it is a mindset more than a process, based on your comment we are Agile when we thinking agile – Mjd Kassem Feb 25 '19 at 14:06

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.

| improve this answer | |
  • 1
    Seconding this. The ISO rules simply say you need a well defined process. If your company decides that process includes SRS and BRS then your company needs to define how, if at all, the agile processes generate those documents. If your company decides that user stories will be the SRS or BRS then simply write that down as your process and follow it to make ISO happy. – Pace Feb 24 '19 at 17:57
  • you mean that is no Agile-Specific ISO, How do I ensure that I follow Agile? many per attempts tended to be waterfall, sorry it seem to be another question. – Mjd Kassem Feb 24 '19 at 18:43
  • I added a bit more to respond to the "following Agile" question. I hope that helps. – Daniel Feb 24 '19 at 19:23
  • A very valuable answer, thank you. Bu I feel like you forgot to actualy answer. Where does the doc fits in? – YSC Feb 25 '19 at 9:55
  • 1
    @YSC yeah, that struck me too. This could get really broad, so I tried to hit the points that seemed needed for the original poster. For anyone interested in what maintaining documentation looks like, I recently answered that on a Stack Overflow question here: stackoverflow.com/questions/54811992/… – Daniel Feb 25 '19 at 13:53

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.

| improve this answer | |

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.

| improve this answer | |
  • developer will implement the code using TDD, but where should they start, i think the testers will write the acceptance test according to the user stories acceptance criteria, the acceptance test then will be as an input for the developer, in other word we are going to make our developer driven by tester and this was my question , no SRS, no BRS, only product backlog items with clear acceptance criteria for all team member – Mjd Kassem Feb 25 '19 at 18:34
  • 2
    Yes, start with BDD failing test and then also write failing unit tests and then make unit test pass and then make BDD test pass – Michael Durrant Feb 25 '19 at 20:10
  • 1
    Hands down, this should be definitely the goal state for each project. As lower the barriers between managers and development, as mature a project is. +1! – Tiago Cardoso Feb 25 '19 at 20:30

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.

| improve this answer | |

Your Answer

