Where are the System Specs in Scrum?

November 27, 20132 min

This was a really good question in the Scrum Practitioners LinkedIn group.  What started out as a short response, became a blog post so I decided to share my ideas here as well.

Scrum is silent on the topic of specifications – it neither requires them nor prohibits them.  I know this is not a very good answer.  As many people will tell, user stories are very common way to document the Product Backlog, but  they are not required by Scrum.  As a consultant, I almost always use user stories, so where do the user stories come from?  Well….that depends – the ultimate consultant’s answer.

For many, many products, project or programs a simple conversation captured in the form of a user story is sufficient.  The user stories are not a replacement for a spec, so do not try to write all the details that would be in a spec on a user story.  There is just not that much room on a 4 by 6 inch index card.  User stories are a reminder that we had a conversation about a feature and what is persisted on a card are the key points we do not want to forget.

However, just because we do not have specs that does not mean we do not need to know the details commonly contained within specs.  The difference in Scrum is that we only investigate the details when the feature is scheduled to be implemented. Essentially, we gather the details just-in-time.  So where do we persist the details?  In the code and in the test cases.  IME, most of the details in the specs are what eventually ends up in code and\or the tests.  So if this is true, why not just write the details in the tests and write the code that passes your tests?  This is essentially Test-driven Development.

For other types of products, or certain types of customers, you need more than a lightweight documentation tool like user stories.  In that case, I would recommend writing some use cases to develop a shared understanding of the system behavior.  I would suggest to stay away from defining up front most of the implementation details.  Focus the use cases on high-level requirements.  For systems that have lots of complicated UI interactions, use low-fidelity, hand drawn sketches.  These sketches are not to document the requirements, but to communicate the intention of the features and help people build a shared understand of the system and it’s interactions.

As you get to more regulated products – where the cost of failure in the terms of hardware, lives lost, environmental impact or certain types of financial transactions – then detailed specs become (mostly) unavoidable.  In that case, I would treat the specs as something you write AFTER the features are completed.  The specs serve as a historical document telling auditors or maintenance programmers what you built rather than using the specs as a design blueprint.