Painless Functional Specs Part 2

What is a Spec?

This Joel Article is a continuation of Joel's previous article on functional specifications. Like most of Joel on Software, this article is a little dated yet there's some wisdom in there that still holds true.

What types of specs are we talking about?

Right off the bat, Joel makes it clear that there are 2 types of specifications. Technical specifications talk about the technical details of the solution, whereas functional specs talk about the features of the program from the User's point of view. Here we are talking about functional specs, not technical specs. We're talking about what the system should do, as opposed to how it should do things.

An example

To make clear what he is talking about Joel includes an example. It is worth reading. You can find it here.

What does it include?

Joel then calls out the parts of a functional spec that he thinks are essential:

• Disclaimer - It's important to note that this document is incomplete. It is simply our best understanding of the problem at the moment. It needs to be a living document and updated as our understanding grows.
• Single Author - Joel advocates for a single author.
• Scenarios - Joel's description of these sounds very similar to the idea of User Stories. These talk about specific users (or types of users) and how they would interact with your product and what they are trying to accomplish.
• Nongoals - This is Joel's interesting choice of words for what is out of scope. I quite like it.
• Overview - This is just the big-picture documentation of the system. A high-level flow chart or architecture diagram or something similar.
• Details - Joel calls this the most important part. What he's really talking about here though is documenting the decisions that are made. These are detailed architecture diagrams, flowcharts, etc.
• Side Notes - These are generally small pieces of information that are only useful to part of your audience. Joel advises to call those out and make it clear who the audience is for that information.

How does it hold up?

Overall Joel's advice here holds up well. It shouldn't be surprising. There is a reason his articles are so popular even after all these years. From a LabVIEW perspective, I would probably add a section specifically on hardware: all the input and output signals with their levels, sampling requirements, desired resolution, etc.

One Minor Issue

I somewhat take issue with his advocating for a single author. I think that the spec should be a group project. We need to make sure everyone has input, so I don't think a single person should write it. Perhaps a compromise is assigning a single person to be in charge of updating it once it is written.

Alternatives

As an alternative to writing out such a spec I a very big fan of the Agile Inception Deck. It does a good job of making sure everyone is on the same page. It is nowhere near as detailed as what Joel is suggesting. I view his suggestion as a little more towards the Design Up Front idea than Emergent Design. To Joel's credit, he does call out waterfall thinking near the end when he points out that the spec needs to be a living document.

Joel mentions that the importance of capturing details lies in making sure all the decisions are captured. I haven't personally used Architecture Design Records (ADRs), but I know several people who have had good success with them. Personally, I've been relying on capturing those ideas in GitLab Issues and/or capturing major design decisions in the Readme.