In agile/scrum, do you write detailed specifications?

Question

In agile (scrum), do you write detailed specifications for your stories/tasks?

Someone said a specification should take 2/3's of your development time.

Is this still 'the agile way'?

Answer 1

We only write specifications detailed enough to convey what needs to be done for the current phase (which is only three weeks long). I am sure this isn't they only way to go about requirements, but to keep the pace moving we realized this was necessary for.

2/3's of the development time seems a little long, but I would guess this depends on the number of people on the team and the amount of communication needed between the members. We tend to have small teams here, maybe three or four people at most for a project (which are always small) so we can quickly alter course if need be. Generally, if something is missed we can quickly get together and figure out what needs to be done. Since there aren't really detailed requirements, it's easy for everyone to read and digest and it's a lot easier to update a short document than a long one, so the document is easy to keep up to date.

Answer 2

We only do enough specification so that we know what we are building, and refine the specification as any problems / holes are noticed. We don't use UML or functional specs - just brief, written cards that describe the functionality we need to implement.

If we do spot holes, we refine the spec and reestimate (if necessary).

Answer 3

With Agile methodologies it's the user stories that are the specification. These should be sufficiently detailed to enable anyone to code from them, and only be for those stories being implemented this phase.

There's usually assumed to be not much point in writing a detailed specification of the actual code too far in advance as it's highly likely that it will become out of date during subsequent phases/sprints. Specifications for complex or critical pieces of code will always be required.

If you think a task requires a specification then it probably does. Some of the more mundane aspects of the project probably won't need specifying to the same degree or even at all.

Answer 4

A user story in XP is only a "promise to have a conversation" with the user. When the developers start work on the story they sit with the customer, discuss the details of what the user needs the system to do, capture that knowledge as automated acceptance tests, and then start implementation to make those tests pass.

The acceptance tests are the closest equivalent in XP/agile to detailed specifications. They are rigorous and are automatically validated. The machine validatable aspects are often associated with human readable explanatory text, but the less of that there is the better because it can easily get out of sync with the parts that are checked by machine.

An important skill for working on an agile project is the ability to write tests that are executable and also clearly communicate the behaviour being tested to non-technical users. People are starting to publish books on this topic. Two notable titles are:

• Bridging the Communication Gap: Specification by Example and Agile Acceptance Testing by Gojko Adzic
• Fit for Developing Software: Framework for Integrated Tests by Rick Mugridge and Ward Cunningham, Prentice Hall, 2005.

Answer 5

2/3 seems about the right percentage to do an agile specification of talking to the customer to understand the story details and writing all of the automated tests.

Answer 6

With regards to the question

Is this still 'the agile way'?

It's probably not the ideal agile way, seeing how you worded your question. "Detailed specifications/tasks" tells me that they're likely not user stories and are probably more traditional-style formal requirements. Yes, you can have them but they should be references by the people writing or preparing the user stories, not part of the development.

And then as developers, your task is to read, clarify, and understand user stories; not write specifications. If you're doing most of the writing, then it's really more of a hybrid of partial adoption of agile.

Answer 7

Hi there, interesting topic, in Scrum you normally use to say specify "Just enough... just in time", which brings you to think again about the Agile Manifesto: "Working Software over Comprehensive documentation" and "Customer Collaboration over Contract Negotiation" :-)

If you consider - only for a second - the PO as your customer, and you think agile, that you have to communicate and negotiate with him, so full-bandwidth against writing.

Specification have been made to be the "Contract" between Product Management and Team, you do not want that... you have to try to avoid any "barrier" that will break the "agile" thinking, pushing the Product Owner again to toss Specs at the other side of the wall and get them signed-off ;-) Try instead to write "Stories" and use them as reminder, and lightweight specs, so that the team will remind reading a story the discussion undergone with the Product Owner during the Sprint Planning Meeting.

Tell the PO to break down and groom the backlog as much as it is needed to give the team a choice for the upcoming team commitment, not more (would be waste) not less (they may not feel they have a choice, and you may end up limiting their commitment).

I hope this helps :-)

Answer 8

Personally I like to have more information up front. I have learned the hard way with a project I recently finished up that not having enough information about the design up front can lead to a lot of reworking of existing code later.

I still like to do iterative development, putting code out there every 2 - 3 weeks, but I like to have a better overall picture before I even get started.

Answer 9

No, it is not the agile way to write detailed specifications. The level of detail in your story card requirements is dependent on the team, the number of dependencies and maturity of the line.

If you have a distributed agile team, you will need more detail in your requirements. Also, if you work in a large enterprise and your system has many dependencies, your story card will have more detail. Also, if your business partner is not able to sit with the developers or is uncertain of what they want, it pays to spend time with them prior to the iteration to capture what is needed.

A good template for an effective story card is to capture a screen sketch (if the app has a GUI), a description of the business purpose and value of the feature. A primary and alternate work flow and most importantly the acceptance criteria. By capturing the acceptance criteria, the business partner (product owner) invest the time to make clear what the software must do for him or her to sign off on a developed story card. This criteria will drive the unit tests and automated functional tests. Your defect rate will drop and your team will spend more time developing story cards and less time fixing defects found in UAT or production.

You should have not have more than one iteration of undeveloped story cards written at any given point in time. If you build up a larger number of story cards you have inventory, thus waste. The result of the current iteration may cause change to a story card inventory thus causing unnecessary rework.

If the team employes the agile engineering (XP) practices, the arch and design will emerge and the code will remain flexible and easy to change as the requirements evolve. Furthermore, the automated unit and functional test will enable the team to refactor the code with courage and confidence.

Answer 10

In my experience, it is best to only document features that you will program during the current iteration. For each feature, you need to have enough documentation to be able to:

• Explain what problem this feature solves (what value it brings to the customer). This will help programmers understand why they are programming that feature.

• Explain what solution has been selected (how to software will be changed to bring that value to the customer). This tells the programmers what to program.

• Identify the other parts of that application that will have to change because of the new feature (to understand the impact and side-effects of the change). This will tell the programmer all the other things he has to change to make the new feature fully functional and fully integrated with the rest of the app.

In my team, for a feature that takes 4 to 12 hours to complete, we need about half a page of documentation (mostly in bullet form) to document the above items.

Answer 11

If you're using the right language, tools and framework, you shouldn't need detailed specifications.

In the olden days, we used to write "structured English" or "pseudo-code" specifications. They were about as detailed as Python code.

Nowadays, I just write Python and I'm done with it.

Answer 12

I agree with amischiefr.

Sometimes it IS necessary to have a technical spec before sprint development begins. I know this is against 'vanilla scrum', but when the entire application depends on a correctly defined application data lifecycle or event design, you have to define that first. Building a partial view and refactoring isn't an option.

Likewise, behavior of UI. If you are dealing with a complex domain such as Health, you may need to specify screens at a greater level of detail than you can fit on a card, and you may need to do this before the sprint.

In our case, both of these are done as 'gates' that are required before stories can leave the backlog. You can't schedule a story into a sprint if it doesn't have the application architecture defined adequately, and the UI defined adequately. It doesn't apply to all stories, but we do run a check each time.

If we don't do this, we end-up with software design from ad-hoc decisions. The software will work, but it can bite you in a future iteration, and the cost is high. Right now we are facing the reality of scrapping some previously built software because the technical design wasn't correct. This resulted from a failure of the design process, which in this case couldn't be incrementally achieved by 2-week sprints to 'done'.

I suspect this depends on the domain you're working with. If the domain is very complex, it applies. If the application architecture is already reasonably understood, design-as-you-go can work. When the domain is new to you, upfront technical design is a great investment to set your sprints on the right track.

Some apps are harder than others ... which is why agile processes adapt.

Just my $0.02c.