Requirements
Why are we doing this?
…failing to write a spec is the single biggest unnecessary risk you take in a software project. It's as foolish as setting off to cross the Mojave desert with just the clothes on your back, hoping to "wing it." The most important function of a spec is to design the program.
What exactly are we doing?
Requirements documents in some settings may be very long and formal. Our requirements documentation will be fairly informal, probably 1-2 pages in length. Use the report template provided here. Your document must include:
- High-level description/vision of the product.
- A list of the functional requirements.
- A list of the non-functional requirements.
- Potential project risks.
- Definition of done.
The examples below were extracted from prior semesters, just to give you some ideas of what to include (every project is different, so you should do what makes sense for your situation). Note that these pre-date our use of a common report template for all projects.
High-Level Description/Vision
Often Scrum’s emphasis on 'getting work done' is misunderstood as a rush to develop with not enough thought to where the project should be going. Don't make that mistake. Every Scrum project needs a product vision that acts as the project's true north, sets the direction and guides the Scrum team.
- Roman Pichler
Starting points:
- https://www.romanpichler.com/blog/tips-for-writing-compelling-product-vision/
- https://www.atlascode.com/blog/creating-a-software-product-vision-statement/
Examples:
Functional Requirements
These specify functionality that must be included. They should:
- state what needs to be included (but not how it will be implemented)
- be specific and testable (e.g., include a login page)
- avoid subjective requirements (e.g., easy to use)
Examples:
Non-Functional Requirements
Functional requirements are supported by non-functional requirements (also known as quality requirements), which impose constraints on the design or implementation (such as performance requirements, cost constraints, security, or reliability).
Risks
Identify both technical and skills risks. A full discussion of software risk analysis is beyond our scope, but you might want to skim a few links, such as https://www.castsoftware.com/research-labs/risk-management-in-software-development-and-software-engineering-projects.
Definition of Done
- List minimal useful feature set
- Describe any tests the client will run before accepting the software
- Specify how the product will be delivered.
Use cases and Stories
For your product backlog, these descriptions of use cases and stories may be helpful.
Final Thoughts
Also from Joel Spolsky. A giant reason to write specs is to save time communicating:
- Everybody on team reads spec before doing detailed design
- QA reads spec so they know how to test
- Marketing uses spec to write sales fluff
- Customers use spec to ensure team is building the product they want
- Tech writers read it to write documentation
Without a good spec, it’s impossible to estimate & schedule.
