Atex Blog

Thank you for subscribing

Follow The Atex Blog

All Posts
Latest Posts
Most Viewed Posts

Atex Homepage

Six essential rules for writing system specifications

After 20+ years in the business, the Publisher had been through dozens of system implementations. Editorial, advertising, circulation, pre-press, post-press. You name it; he'd bought it. He'd installed it. He'd replaced it.

He brought this exabyte of experience with him as he walked into the executive conference room. The supplier's team sat to his left, all suited up with laptops poised. The customer team -- his team -- sat together on his right. Without a word, the Publisher walked up to the white board, picked up a red dry-erase marker and wrote in large, neat upper-case letters: WINDSCALE.

Turning to his audience, he pointed to the board and punctuated each letter with the red marker as he spoke. "What Is Not Down in Specification Costs A Lot Extra," he said to the group. Then he turned and left the room in strategic, deferential silence.

Through this simple, albeit melodramatic gesture, the Publisher communicated to the entire team his belief in the importance of the specification process when launching a new project. In addition, as the project's sponsor, he acknowledged the specification as the unifying document that describes what the system will and will not do -- and ultimately, what his company will and won't pay for.

There's a problem, however. Even if every person at that table agrees the specification is important, there are two widely different views as to what a spec actually is and does. The customer team would say that the specification defines what they want the system to do. The supplier team is likely to say that the specification describes how the system will work. The distinction between what and how often leads to misunderstandings that can jeopardize the success of the project.

The search and selection process often begins with a Request for Proposal (RFP) detailing all the things the customer wants in a new system. In the supplier's eyes, the focus is on implementation. The supplier may respond to the customer's RFP with a proposal describing all the features and functionality that their system has to offer. The customer is talking expectations, while the supplier is talking execution.

Disconnects occur whenever the customer feels their RFP very clearly states what they want the system to do, and the supplier feels their proposal defines exactly what the customer will be getting.

The trick here is to recognize that the specification must encompass the requirements as well as the solutions. The what is certainly important. So is the how. But, to ensure that the specification meets the objectives of both the customer and the supplier, the focus also needs to be on the why. If every individual gathered around that conference table can agree why each item appears in the specification, then both parties will be able to see the issues from the other's perspective.

Here are my six "Windscale Principle" rules to help produce good, clear specifications leading to highly successful projects.

1. A bad beginning makes a bad ending.
This ancient saying from Euripides is relevant today. Our Publisher understood this when he set the agenda for the project team during the kickoff meeting. The specification process is the foundation of the entire project. All subsequent tasks -- including design, development, manufacture, delivery, training, parallel and live operation -- will suffer if the time is not invested early in the project to write specifications that everyone agrees to.

2. Memories fade a lot quicker than ink.
Don't rely on collective memories when defining requirements. Complex projects involve many players, some of whom may be gone by the time the implementation phase rolls around. Verbal promises, assurances and commitments are difficult to verify, and are wide-open to misinterpretation. The specification should be viewed by all parties as the official rulebook for the project. If disputes arise, the team should be able to turn to the specification as the definitive document that captures each deliverable.

3. Keep it simple, succinct, unambiguous, precise.
The awkward acronym notwithstanding, this rule helps to ensure that everyone interprets the specification the same way. Each item in the spec should express a single thought. Simple declarative sentences should be used. With large projects, several different people often share in the spec'ing duties, so it is important to maintain a consistent writing style.

Use words such as "will" to state facts, "shall" to state requirements, and "should" to state goals. Avoid words that can cause misunderstanding, and that might lead to disputes. Words like "etc.", "TBD" and "fast" do not belong in a specification because they are vague, confusing and not verifiable. To allow validation, the terms must be specific and quantitative. A sentence such as, "The system will provide rapid, user-friendly access to menus..." may mean one thing to a customer and something entirely different to a design engineer. Try to choose words that are measurable, objective and straightforward.

4. Know the difference between necessities and niceties.
When putting together a specification, you do not want to end up with a one-off solution that will take many months to develop and install, and which will be difficult to upgrade and support in the future.

If there is any doubt about whether an item in the specification is really needed, ask yourself: What is the worst thing that could happen if this didn't get included in the final system? If the project team cannot come up with an answer of substance, then the item is probably not really needed.

5. No bull, no bullets.
Good specifications should be written in sentence form. But don't over-specify. People often write down everything they can think of, with the hope that the reader will somehow grasp the real requirement. Avoid long, run-on sentences that convey more than a single thought. And, try not to use too many bullets when listing requirements, as bullets by themselves often lead to misunderstanding.

6. Sponsorship is key.
Finally, as our Publisher illustrated, it is essential for the team's sponsor to buy into the importance of the specification process. Poorly written or incomplete specs can add many hours of rework time to the project, so the time investment at the beginning of the project is always worthwhile.

A good sponsor facilitates the specification process by developing a sense of shared leadership and common purpose. From the outset, the sponsor should take responsibility for guiding the project's mission, building team cohesion, maintaining focus, and resolving conflicts when appropriate. The challenge is great, but the rewards are significant.

Consistent expectations. Shared benefits. On-time/on-budget delivery. Happy end-users. Invoices paid in full. Long-term supplier-client relationships. By adhering to the Windscale Principle, and acknowledging the significance of the specification process, the likelihood of project success will be assured.


Bookmark and Share