I can’t help but question functional specification methodology.  It’s a crucial part of the development process, but how can you be sure it is adding the right kind of value to your process?  I don’t deny that specs are important; it is often the developer’s first line of defense for answering questions.  Some specs look and read like a loosely worded form letter, hardly communicating any concrete requirements for the project.  With that said, let’s get something clear.  Should the spec “know” everything?  If not, that’s okay.  The sooner we can reach a consensus the better.  For the purposes of this blog post, I’ll say the spec doesn’t have all of the answers.

Think about the goals of a finished project.  They are to meet high expectations in terms of quality, performance, accuracy, and reliability.  Should the spec be treated the same way?  If so, how does that happen?  My expectations are probably higher than the average person, but on some level I would like to think that they’re reasonable.

I expect a functional specification to be somewhat enjoyable to read, but useful above all else.  Rather than take the easy way out, I would like to clarify my expectations with a checklist of questions about functional specifications:

• Is the document high quality?
  • Is the document human readable (spelling and grammar)?
  • Is the vocabulary clearly defined, and used consistently throughout?
• Does the document perform well?
  • Does the document answer as many of the obvious questions as possible; actively trying to predict all possible road blocks along the way?
  • Is the document well organized?
  • Can information be quickly located?
• Are the details of the document accurate?
  • Have all points of design been thoroughly researched?
  • Has anyone else peer reviewed its contents?
• Is the document reliable?
  • Is all information within absolutely relevant?
  • Are the images or screenshots useful?
  • Are all details inline, and not between the lines?
  • Is the spec maintained in a timely fashion?
  • Are updates to the spec properly documented in detail?
  • Does the spec have some way of tracking changes?

All of these things pave the way for a well written functional spec.  Aside from a checklist, it might be helpful to further elaborate on my expectations by identifying common problems:

Yes.  Punctuation, spelling, and grammar all count.  Much like meeting someone, first impressions matter.  Think of grammar as a textual handshake; weakness in spelling and grammar gives the writer less credibility.  Writing is hard, but there are ways to make it easier.  At the very least, try adjusting spelling and grammar rules in your favorite word processor for extra strict practice.  Try not to ignore the omniscient squiggly lines. 

Ditch ambiguity—writing in the passive voice is the safe way out.  It’s like saying “the system might work this way.”  Use the active voice to instill confidence in the reader’s mind that there is some certainty to the outcome of the project.  Personally, learning to write in the active voice has been challenging, but absolutely worthwhile.

If I have to read between the lines, I’m already digging too deep.  Programmers are literal thinkers.  We tend to take everything at face value.  If it’s not put in plain English, don’t expect us to grok it.  Try to leave no stone unturned, and be explicit about implied knowledge and reap the benefits.  To some extent, assumed knowledge is like assuming we are all exceptionally gifted mind readers.

Cater to the drive-by reader.  Structure the document in ways that are easy to navigate.  It shouldn’t take any longer than fifteen to twenty-five seconds to find something in the spec.  Make the spec only as long as it needs to be.  Just like emails, people will naturally skip the body and go for the punch line.  Use lists to break up steps or detail oriented explanations.  Ancillary data can go into text, but keep the key parts visible to the scrolling eye.  Page breaks are a good way to clearly delimit autonomous sections.

Copy + Paste = Fail.  Period.  Keep things DRY (Don’t Repeat Yourself).  If you had to copy and paste, it probably wasn’t worded clearly enough the first time.  Plus, changes to the pasted text only mean more work.  Pasting paragraphs, even pages of text (really?) into a spec is counterproductive.  In some situations, jilted sections of pasted text could possibly be taken at face value.  That’s a risk I’m not willing to take.

Find an effective way to communicate changes to the spec in detail with everyone involved.  Whether it’s writing emails, checking into version control, or including it in the document itself—it’s bound to be helpful to someone.  A one line history summary is not sufficient.  Try sending an email that includes a summary of the latest changes, snippets from updated sections, page numbers, and a preview of what is in store for the next update.

Joel Spolsky posted a sample functional spec, and it’s worth skimming as a point of comparison.  I also recommend his series of essays entitled “Painless Functional Specifications.”  While I won’t argue that functional specifications are necessary, I believe that poor execution is equally destructive.  For them to truly add value to a project, they need some tender love and care.