Today, I bring you a little template that's useful to have on hand for quickly whipping up something you can have your colleagues review.
There are much more extensive templates out there that you should also look out for inspiration.
Ideally you would couple an agreed-upon design review process, as well as keeping an in-document list of reviews/approvals or via some other tracking mechanism.
Happy spec'ing!
Overview
- A one-paragraph explanation of what this document is trying to do.
Background
- Things you should know before getting into the document and context-setting.
Goals / Product and Technical Requirements
- What things you're trying to get done.
Non-Goals
- Things you might think this document could do, but you're not intending to.
Assumptions
- Things you're going to take for granted but might otherwise significantly alter this document.
Current Design
- If there's an existing thing in place, describe that in brief.
Proposed Design
- Describe what you want to do in enough detail that you can get useful feedback.
- Depending on your domain, you might have a list of common areas that you might want to touch on regularly. Those might include the following sections, but you should add/remove as needed even on a per-document basis.
Accessibility
Internationalization
Performance
Cost
Scalability
API Surface
Include the "header" or shape of your API if you're building a new feature or library.
- Error Handling. It's good to include a paragraph on your error handling strategy. Do you return error codes, result/error values, exceptions, callbacks, set a property/global to be checked, terminate, some combination of these?
- Threading Model. I've talked about various options on specifying a threading model in the past.
Sample Usage
Include snippets of what code you expect API users to write.
Compatibility
Platform Support
Test Approach
- How will you know the thing works? Manual verification, automation, someone signing-off, some important scenario working, combination thereof?
Project Tracking
- How will you track the work happening to make this a reality?
Alternate Designs
- What other things did you consider and decided not to go for?
References
Include a bulleted list of referenced material here.
Tags:
checklist writing
Home