agile / scrum and functional specs

Question

I work in a small team of four devs, one domain expert and one manager. We are looking to move to using scrum to try and formalise our processes.

From what I understand of agile, it seems to be close(ish) to what we are doing anyway. We have a brief document with the overall features our product will have. As we come to code each feature, we sit down and thrash it out verbally, relying on our domain expert for what the customer will want. We then code it, and it gets tested in vague ways by the other devs / domain expert. Improvements get suggested and implemented.

At our last ISO 9001 audit we were (deservedly) reprimanded for lack of any traceability. The auditor wanted some way of seeing we had records of what the product would do, and then testing to prove that it did it.

We are looking to scrum to give us a process for this, along with other benefits, but my reading up so far has not answered my question of where detailed functional requirements are recorded / tested? My understanding of agile / scrum is far from complete, so please correct me if I have misunderstandings.

As an example, let's say we have a user story that says: "As a customer, I need to be able to select a system state of A, B or C". It has an acceptance test that says "I should be able to select state A, B, or C, and the system will change to that state"

Come the sprint where this gets implemented, we sit around and decide that we will build a widget with A, B and C radio buttons, and a "Apply" button. Then we code it.

When this widget is tested, the following problems are found: 1. Selecting B sometimes doesn't uncheck the previous radio button. 2. Sometimes option C is unavailable on the system, and so should be greyed out. 3. When first opened, the initial selection does not match the current system state.

My question is how and where is this recorded? There is no detailed functional spec saying "There will be a widget with three radio buttons. When the widget is created, the current radio selection should match the system state" blah blah. Given the lack of this document how are we supposed to prove that the system does or does not do what it's supposed to to an auditor?

Answer 1

Given the lack of this document how are we supposed to prove that the system does or does not do what it's supposed to to an auditor?

Why is that a given? There is no rule of scrum that the only thing created is software. Make your acceptance criteria include "done when we have a detailed ISO 9001 compliant functional specification". Or, make that a separate story altogether: "as a developer on an ISO 9001 team, I need a functional spec so that our software is compliant". Create the spec, and then from that you can come up with the stories necessary to implement that spec.

---

In the comments to this question, @Pete expressed concern that if the spec were a story, how can the product be "potentially shippable" if all that is delivered after an iteration is a spec?

Look at it this way: your end product is composed of many pieces: A, B, C, D, etc. At the end of each iteration you should have one of those pieces finished and potentially shippable, right? When A is done it should be potentially shippable. When B is done it should be potentially shippable, and so on.

Where does it say that A must be a software product? A can be potentially shippable even if it is simply a functional spec, or a test case, or a DB schema, etc.

Don't look at your functional spec like it is somehow outside of your product. Instead, see it as an integral part of the product you are delivering, on equal footing with software, DB schemas, test cases, user guides, etc.

Answer 2

As an example, let's say we have a user story that says: "As a customer, I need to be able to select a system state of A, B or C". It has an acceptance test that says "I should be able to select state A, B, or C, and the system will change to that state"

There's your problem, in my opinion. And Scrum, a project-management technique, which falls in the realms of Agile (don't confuse the two terms), isn't going to help you. But there are other Agile techniques that will. For this scenario, behaviour-driven development will be the place to look.

To explain why I think that's your problem: Your first statement isn't really a user requirement (Feature, in BDD) and the second isn't a behaviour definition (Scenario, in BDD).

Feature: State A

As a customer
I need to be able to select system state A
So that the fires of Mordor will burn

Feature: State B

As a customer
I need to be able to select system state B
So that the orcs will be at the gates

(I am assuming that neither one of these requires the other, so they are separate features.)

Notice the "So that ..." clauses. They are an important part of a feature. If you have trouble writing "So that ..." on each feature then either you don't need that feature or the scope of it is too large. I suspect the latter in this case, hence I've broken it down into the three states.

Your test definition is similar, it doesn't really specify anything. BDD has a Given-When-Then syntax that helps us focus on the scenario we're testing:

Given that I am on the state selection screen
When I select state B
Then the horn of Mordor should sound
And the orc-cages should be unlocked

Note that each clause can have And, But or Or extensions, if needed -- but, in general, When (the user action) should be a single defining action.

Going back to the three bugs you listed:

# Selecting B sometimes doesn't uncheck the previous radio button. 

Given that I am on the state-selection screen
When I select option B
Then options A and C should be deselected

This is a perfectly valid test. Entirely unnecessary if you use standard library radio-buttons, but if you have this bug then you clearly don't, so you should account for it.

# Sometimes option C is unavailable on the system, and so should be greyed out.

Given that state C is unavailable
When I load the state-selection screen
Then option C should be greyed out
And option C should be unusable

Given that I am on the state-selection screen
When state C becomes unavailable
Then option C should be greyed out
And option C should be unusable

Two behaviors that should definitely be tested separately, assuming they are both required.

# When first opened, the initial selection does not match the current system state.

Given that the current system state is C
When I load the state-selection screen
Then option C should be pre-selected

Starting to get the idea? Don't get me wrong though, this is HARD WORK. But being Agile is a lot more disciplined than people think it is. If you're going to get and hold an ISO 9001 accreditation, you're going to need to decide which disciplines are for you and stick to them. If this is too much effort, you probably need to go back to functional specs.

Answer 3

Well I wonder how Agile/Scrum relates to stuff like ISO 9001. ISO 9001 has documentation and processes in mind, while the Agile Manifesto has working software in mind. Even though it does value documentation/documents, the focus is usually on just enough.

The reasoning behind this is that you can write it all down and a week after having implemented it, the customer might change his/her mind. Of course, you can keep the documents in sync, but after a while, you'll notice you're putting a lot of effort and time in your documents.

What is the added value of all this documentation? If the software doesn't work like the client wants, he should tell you. This can be put in a system like VersionOne, TFS, etc. to fall back on later, but I would advise against going to far in all this documentation.

The application as it is, is what should be important. Not what a certain document says.

This is because Agile embraces change and acknowledges the fact that software changes constantly and can't be set in stone.

I'd definitely recommend 'Scrum and XP from the trenches' by Henrik Kniberg. You can find it on InfoQ after logging in, but it's also available here.

In your example, I would think you demo the widget to your customer after a sprint. He would the see it doesn't do what he wants and point this out. This is the moment when the customer can accept or not accept the work you've done. He can also point out what the next priorities are. Possibly, he has other priorities first. Or he might say you have to fix that.

In the next demo, he might see the widget working as expected and say so.

Maybe you could write this stuff down in a sort of meeting notes. But in the end, I would still be critical and ask what the added value is of ISO 9001. Have you built better software in a faster and more efficient way because of it? Or do you now have a big database of documents and processes, blocking your ability to be agile?

I understand you will want the ISO 9001 certification anyway, so I would advise you to document your processes as little as possible, because in Agile development, you should be willing to constantly change your processes. Constanstly seeking the best way to go forward. Constantly being critical of oneself (this is what the retrospectives are for).