The Joy of Specs

Overview

Software projects can be a nightmare: every step, from concept to rollout, is subject to functional misinterpretations, blown budgets and wildly inaccurate time estimates. And when the project is finally finished, the client complains it still doesn't do what they want. At least this is according to the stereotype of a typical software project. While most projects don't fare nearly that badly, the fact remains that developing a software project is often fraught with uncertainty and waste.

 

What's that? You have no problem planning and executing a project and you never go over time or budget? Congratulations, you're part of the extremely small minority that has significant control over your clients, management, time, budget and technology. For the rest of you who deal in real-world projects, read on.

 

While there are many factors that contribute to the downfall of a project and many ways to mitigate or alleviate those problems, there is one thing you can do that will give you the most bang for your buck when it comes to ensuring your project gets completed successfully: write a spec. Simply put, I've found the spec to be the most neglected, yet most necessary, part of every single software project I've worked on. In fact, if I were to formalize this into a development methodology I would describe it as "spec-centric."

 

My completely off-the-cuff ballpark estimate is that something like 80% of all projects are never formalized by anything resembling a real, useful spec. At best they are defined by a series of informal phone calls, emails, meetings and memos, the content of which are stored, at best, in a series of emails or memos and at worst in the heads of those who read, wrote and discussed them. While this may be acceptable for a few particularly small, limited projects, it's woefully inadequate for most projects. Of the 20% of projects that do end up with a spec, only about 20% of them (or 4% of all projects) are adequately detailed. No wonder software projects are such a nightmare!

 

These numbers are merely informal (albeit educated) guesses that have been extrapolated from my experiences, so don't take them too literally. My point is that only a pitifully small percentage of all projects are ever guided by a well-written spec. This must change if the general state of software development is to improve.

 

In the following pages I'll describe why a spec is important, what makes a good spec, and how to write one.

What is a Spec?

Before we can discuss the importance of a spec, let's back up and define what a spec really is. In general terms a spec is simply a formalized description of the program's desired functionality. So strictly speaking, a sentence such as "The program should allow users to calculate their income taxes" is a spec. It's a very broad, sweeping, vague spec, but it's a spec nonetheless. (More realistically such a short description should really be called a "statement of purpose" but now we're getting into semantics.) Of course a truly useful spec would contain much more detail.

 

A spec serves two primary audiences: the programmer and the client. From the programmer's point of view the spec should contain enough details for them to complete the project. From the client's point of view the spec should contain detailed enough requirements to describe the business objective of the software project.

 

I'm using the terms "project," "programmer" and "client" in the general sense. The "project" may be a standalone program or a series of programs, and may include several disparate hardware and software components. The "programmer" may be several programmers or teams, either working in the same office or in remote locations. And the "client" may be a single person, a company, or another department within the company that is developing the project.

Frequent Objections

Most people cite one or more objections when making excuses to avoid writing a spec. Here are typical objections I've heard, along with my response to each:

 

-        "Nobody ever reads specs anyway so it's a waste of resources to write one."

 

Without a spec, how are the programmers supposed to know what to write? How is the client supposed to confirm whether the program is working as requested?

 

-        "Our requirements are constantly changing. Why not just write the spec once the requirements have been finalized?"

 

The requirements are the spec—once they've been formalized, that is. If they keep changing you'll have to pin them down sufficiently before you can write the spec.

 

-        "It's impossible to write a spec! No single person knows enough about the project to write one."

 

Then either make it one person's business to gather that information and formalize it, or assign that task to the people who are qualified.

 

-        "We don't have the money, time or resources to write a spec. We simply can't afford to do it."

 

I could be snarky and say you can't afford not to do it but that would be, well, snarky. The relatively little resources you devote to writing the spec will be paid back with interest when your project goes much more smoothly and comes in closer to the estimated time and budget than it would have had you not written the spec.

 

-        "We already wrote a user manual. Why do we need a spec, too?"

 

The user manual is for end-users. The spec is for the programmers and the client (i.e. the individual, group or organization that decides what features will go into the project).

 

-        "Our code is self-documenting."

 

Even if that was true, comments in the code tell you only what the program is doing (provided the comments are even accurate), not what the client intends it to do. Besides, only programmers should read source code; clients and managers are happiest when reading short prose in the form of business-speak memos, not source code.

 

-        "Our employees are very smart. They don't need a spec."

 

No matter how smart your employees are, how are they going to transfer their knowledge to other employees quickly and efficiently, especially if they've left the company before the new employees have been hired?

 

-        We follow the Extreme Programming methodology; user stories are the only descriptions we need.

 

In the XP world, user stories are written by customers in their own language and thus are often incomplete, inaccurate, or misleading. A properly written spec combines user stories and additional technical requirements and normalizes them into a universally-accepted, complete document that all parties can refer to and agree on.

 

-        Specs are monolithic. That is so old-school.

 

The whole point of a spec is to be monolithic, at least in terms of aggregating information; a spec should be the single source of all requirements, questions and answers regarding a project.

 

However, the actual execution of a spec doesn't have to be, say, literally a giant monolithic Word document that only one person ever gets to touch. It can be, for example, a Wiki; a blog; a newsgroup; a BBS; a collection of multimedia files; or anything else that works for you.

How Detailed Should The Spec Be?

A good rule of thumb is that any details left unanswered by the spec should be trivial enough that the programmer can either guess at the right solution or get simple answers from the client.

 

More important, as the project progresses and the unanswered questions get filled in, they should not cause the majority of the spec to change. If they do, then your spec wasn't written properly to begin with.

 

An improperly written spec can be caused by several things:

 

-        poorly defined requirements: if the requirements aren't clear, how can the spec possibly be clear?)

-        incomplete spec: if the spec doesn't contain enough detail then the programmers will have to guess

-        poor writing: if the person writing the spec is a poor writer, the spec will be useless

Who Should Write the Spec?

Ideally the spec should be written by either the Project Manager or by somebody who reports to them. Depending on how roles are filled in your organization, and on your employees' skills, the spec may a joint effort between several people.

 

Details of good technical writing practices are beyond the scope of this article but at a minimum the writer must have a good working knowledge of the technical aspects of the project and be able to express that knowledge clearly. They should be clear, concise, consistent, and anal-retentive, and should enjoy revisiting their words multiple times, tweaking and revising things until they are just right, but never being quite satisfied with anything they've written. And yet, they must have the foresight not to get bogged down in the technicalities of writing.

Using Your New Spec

You've finally done it: you've created your spec. Now what?

 

Read it over again several times. If you can't find any unanswered questions or inconsistencies, either you're not reading it carefully enough or you're simply not qualified to edit your own spec. At the very least, questions in the spec should be noted as "TBD" items.

 

Give it to the programmers to read over. (Of course, you've been doing this all along so the programmers can provide feedback while you've been writing it, right?) Programmers always come up with new (read: important) questions.

 

The Spec is your bible. All questions about the project should be answered in the Spec. Can't find the answer to your question in the Spec? Call a meeting, come up with an answer, and add it to the Spec! Is the Spec vague or ambiguous about a particular feature? Call a meeting, arrive at a decision and—you guessed it—add it to the Spec!

 

Don't like meetings? Think they're a waste of time? No problem; how you manage your employees is largely outside the scope of this article, so you should feel free to change "call a meeting" to "send an email," "make a phone call," "ask the programmer to step into your office," or "walk over to the programming department and ask them."

After the Project

Your project is finally over. What do you do with the spec? Trash it? Of course not! It contains a veritable gold mine of information and serves as the blueprint for your next project's spec. It also serves as historical documentation of your project that you can always refer to if necessary.

Conclusion

Nobody ever got fired for writing a spec but plenty of people have lost their jobs because of projects that weren't properly specified.