John Coder

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.

"You read too much," I'm told by a well respected peer (whom I assume was only kidding...).  Alas—It's true.  My cup runneth over with things to read.  I can't help it if I find things like Development Abstraction,screwing (yeah, you have to click on it for it make sense...), and building monsters in the garage immensely interesting.  Make no mistake about it, reading is good for you.

The Internet leaves us with no shortage of things to read.  A lot of it is crap, but there are some good things out there.  What I find daunting, and often dangerous, is that one article leads to another.  I keep turning the pages of the newspaper, but it never ends.  It's dangerous because it can lead to information overload, but we all know our limits.  I learn from the things I read, but I think there's something much bigger going on.

I'm getting better at basic things we've learned to ignore since grade school—reading and writing.  Ultimately, it's practice and repetition that makes us better at these activities.  People who read are often better at writing.  Furthermore, people who write and write often improve their writing skills.  It's my hope that this somehow reflects in my day to day ability to communicate in the work place, and who knows, maybe even improve the quality of my code.  The not-so-secret path to getting better at writing code is to write code.

Blogs are some of the best ways to get your opinions and information out into the world.  I'm not the first to discover this by any means, but it's a way that I've become greedy (for all of the FREE knowledge people are willing to share, as long as you're willing to read).  I subscribe to many RSS feeds, and often try to read anything that pops up in it.  Take the best and leave the worst.

*Disclaimer:  While reading blogs, you may find yourself saying:

"I once read a blog post about ... [ blah, blah, <nerdy topic>, blah blah ]" – me

So how can I write a blog post, totally self motivated, and then make a jab at my own character flaws?  Well, you're just going to have to figure that one out for yourself. 

Welcome to my blog!  You maybe wondering "Why a blog?"  The answer is simple.  Engagement.  No, not marital engagement--more like active engagement.  On my own time, I try to stay on top of what is "up and coming" in the developer community.  When I find something interesting, it might find its way to this blog.  It could be related to a specific technology like C#, ASP.NET, JavaScript, Visual Studio 2008/2010, or SQL Server.  It might be a philosophical post involving design patterns and industry-wide best practices.

How is that active engagement?  Well, #1 indicator of success is that you've gotten even this far in the blog post.  If you (the reader) has found even a single blog post worth reading and you (hopefully) even learned something, then it was all worth it.

Blogging is a way for me to write, and thus become a better developer.  During an interview about Stack Overflow, Jeff Atwood advised that developers should blog about everything (blog, blog, blog).  Stack Overflow is a place for less known, but fantastic developers to gain presence in the community.  I found this to be great advice, especially if you're able to blog about something worthwhile time and again.  That lead me to Jeff's blog Coding Horror, and furthermore to an article titled "Is writing More Important Than Programming?"  In the article, Jeff refers to some advice from Joel Spolsky to college students:

"The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it's not whether they prefer Python or Java. It's whether they can communicate their ideas. By persuading other people, they get leverage."

As I post things that I've learned, it is important to consider that the ways I am showing are NOT always "the perfect way" to do something.

I hope that future posts may spread inspiration and insight.  Please feel free to comment (in fact, I encourage it).  Let me know if there is something you would like me to post about, or if you would like to see some more in-depth coverage of a certain topic.  Thanks for reading my post, and I hope you return with each new entry.