Writing software involves a lot of backing yourself into corners. For even the simplest-seeming program, you find yourself adding duct tape and chewing gum to satisfy different requirements and logic bugs that come up. Then you gradually whittle it back down and end up with a few simple lines and it’s bewildering how you were too dumb to have not just written the nice simple thing from the start. The beauty of specs is that you can do most of that backtracking and whittling down and rethinking before you start coding.
Previously on the Beeminder Blog we described a thought experiment for how to tell if you’ve written a functional spec. It was like a nonconstructive proof that you’ve written one. Is it the plausible output of turning the final source code into prose and subtracting everything irrelevant to your users? By popular demand (among a small but very smart subset of you), we’ve expanded that into a handy checklist you can go through as you’re spec’ing. This is once again heavily inspired by Joel Spolsky’s classic series, “Painless Functional Specifications”.
1. Front Matter
After the title, include the author, a last-modified date, and the current spec level (0 to 0.5). That serves as a disclaimer and as expectations management.
2. State the Problem
This helps overcome initial writer’s block, for one thing. More importantly, making this part very clear can totally change what happens in the rest of the spec, including the rest of the spec not being written at all if you decide the problem is not one you need to solve after all.
3. Nongoals
State at least one feature you won’t include, a use case you won’t consider, or something more general like not caring about performance or aesthetics.
4. Overview
Write an overview / abstract / executive summary / tl;dr / precis. This might be a wild guess initially. You can keep changing it as you figure out what to build. Which writing the rest of the spec helps you do! (See also Blog-Post-Driven Development.)
5. Open Questions
Put an “Open Questions” section at the end for dumping everything you’re not sure about. All of those things need answers or to be moved to a “Future Work” section before you have a functional spec. You want to start this before you get to the meat of the document because it’s invaluable as a place to dump what-ifs that you’re not ready to think through yet. Otherwise those can constantly derail you and make the spec-writing overwhelming.
6. Use Cases
Describe a use case in so much detail that it helps to give the hypothetical user a name. Usually you want to do this for every possible stereotypical user, like, in Beeminder’s case, Diligent Debbie with a do-more goal to dig ditches and Lazy Larry with a do-less goal for lounging around looking at lolcats.
7. 😂
Make a joke or make something rhyme or add an easter egg or do something that makes your spec fun to read. Emojis if you’re desperate I guess?
8. Pseudocode
Write at least a line of pseudocode for some of the business logic, including picking names for relevant data structures or database fields. See our previous post for what we mean by business logic.
9. Web/UI copy
Include a snippet of webcopy for some screen, popup, or error message.
10. Sidebars
Add at least one sidebar for a technical note or historical debate about alternatives. Anything not of interest to your whole audience — programmers plus bosses plus sufficiently fanatical users — should be sidebarred, i.e., made visually obvious that it can be skipped without hurting the narrative flow.
11. Decisiveness!
Purge every “then we could either” and “maybe we should” until the whole thing is coherent and decisive. This is hard to do. I recommend taking it to the extreme of rephrasing everything from future to present tense. The spec describes what is, not what could be or should be or will be. (Again, Blog-Post-Driven Development is relevant here.)
12. Gedankenexperiment
You can tell this one’s important because it’s in German. And because it has its own whole Beeminder blog post. Do the code-pasting thought experiment from our previous post on spec-writing!
Of course this is all much easier said than done, and Joel Spolsky has a lot more tips, like reading and rereading every sentence, putting yourself in the shoes of your readers, making sure everything is as simple as possible and is understandable and motivated by what’s come before. I also highly recommend Slate Star Codex’s Nonfiction Writing Advice if spec-writing (or any writing) is your job.
Image credit: Faire Soule-Reeves. Thanks also to Bee Soule, Christopher Moravec, and Luke Barone-Adesi for reading and discussing drafts of this.