Thoughts on Writing Software Requirements

I’ve had notes sitting around for months for a post on writing software project requirements, but Brett’s piece last Friday on Estimating Software Projects inspired me to pull them out.  Writing and estimating requirements is painful to most everyone involved, highly problematic, totally not hip – and essential to well run projects.  But since it’s probably just as painful to read about writing specs, I’ll keep this bullet-pointy 🙂
Benefits

• The developer builds a fuller understanding of the client’s needs
• The client is forced to think deeply about the requirements of various features
• The client better appreciates the complexity of the app (that “Oh, I didn’t think about how feature C leads to requirements X, Y, and Z” moment)
• The client gains confidence in the developer’s grasp of the project’s details – and the developer is more likely to get more money for the project
• QA has a starting place for writing a test plan

Dan Milstein’s No Deadlines For You post, while advocating against estimates and specs, includes good advice for writing them: aggressively (but politely) interrogate the client about the actual underlying problem, rather than their proposed solution.  When possible, help them focus on minimizing the feature set in the first release to reduce the risk and delay before the product is in the hands of the software users.
Brett’s point on estimation applies equally to writing requirements:

Projects where we’ve encountered the most success and happiest clients are those where we’ve maintained a steady rhythm of delivering releases demonstrating continual progress along with a view of the pieces that are left to be built along with [a set of requirements for] the effort still to come. The secret isn’t [writing requirements], it’s [re-appraising requirements], all the time.

Tips

• Write one paragraph per requirement
• Fearlessly subdivide that paragraph into new requirements until each one feels atomic
• Record assumptions so that readers have a chance to correct them and future developers have a better understanding of the thought process behind a requirement
  • For example, “Assumption: directions will be shown in Apple’s Maps app.”
• List risks for perilous requirements to warn both clients and future developers, even if they seem obvious
  • For example, “Risk: Apple may reject a parental gate that only requires the addition of one-digit numbers”
• Use one heading per requirement.  An automated table of contents built from these headings provides an easy means to a simple list of requirements
• Include non-functional requirements that have a high impact on cost, like:
  • what platforms are supported?
  • how many users or how much data is expected?
• Keep scratched features in an “Out of Scope” section in case a client remembers requesting a feature but not later removing it

Further reading

Books and papers

• Writing a Software Requirements Document [pdf], by Tanya Berezin
• Writing Effective Use Cases, by Alistair Cockburn
• Software Requirements 3 and More About Software Requirements: Thorny Issues and Practical Advice, by Karl Wiegers

Joel Spolsky’s extensive posts

• In Why Bother?, Joel reminds us of the time saved versus blindly grasping for requirements during iterative development
• In What’s a Spec?, he recommends specification sections like scenarios, non-goals, details and side-notes
• In But… How?, he advocates hiring a program manager who is skilled at writing specs
• In Tips, he suggests helping the readers with humor and simplicity

Sample specs and software

• We use shared Google docs for the requirements (and spreadsheets for the accompanying estimates).  Particularly useful features are:
  • Simultaneously writing the document with a colleague
  • Sharing with clients, and giving them read-only or comment permissions
  • Using the comment system to collaborate on sections without giving up ownership
  • Automatically generating a table of contents
  • Tracking changes to figure out what’s new when a long document undergoes revision
• Joel provides two example specifications: What Time Is It, and his actual Copilot spec
• A class project Virtual Art Viewer spec [doc], from Richard Taylor at UC Irvine