Get Control! An Introduction to Process and Documentation Parts 1 - 5 - Connecting the Dots

Part 4 - Write Great Specifications

The foundation of every process is the actual words written in the documents, not the document format or methodology used. In the next few pages, we'll explore effective ways to capture requirements and other important data. To start, we'll look at the classic documentation types, then, we'll discuss some practices you can use to maximize the effectiveness of your documentation efforts.

Standard Document Types

Functional Requirements Documents

Perhaps the most important category of document types, a functional specifications document outlines what the application will do. It contains every behavior, activity, reaction, event, or other action that an application can perform. At a very high level, these might include:

"The application will back itself up on a nightly basis"

Or:

"A JavaScript validation system will prevent users from making reservations for dates that are already in the past."

Obviously, these are simplistic examples and the above requirements could be expanded into a volume of notes and details. They do help to illustrate the distinction, though, between functional specifications (part of the general functional requirements of an application) and other types of information that document what an application is, how it should be built, or who will build it. For example, the following information is useful, but would not be part of a functional specifications document:

"The system will be built on a platform consisting of RedHat 9.0, PHP, MySQL, and Apache." (This belongs in the technical specifications.)

"Client must approve all technical and functional documentation prior to development." (This belongs in original contract/agreement.)

"The application can be expanded by adding more servers." (If this specification continues to explain how the system will react to such expansion, it could stay. However, it is probably best mentioned in a technical specification document as part of the platform discussion.)

Although it may seem arbitrary to maintain such a restrictive interpretation of the term 'functional requirement', having a focused specification document has been proven to improve documentation quality in general by allowing each document to be concise, simple to read, and formatted for its specific purpose. Requirements and specifications, being the most important information in the entire project, deserve a document of their own, and that document will be more useful if it's kept distinct and targeted.

As a general rule, the exercise of documenting requirements will lead the participants into an ongoing period of exploration and discovery, during which each requirement leads to more questions, which, in turn, lead to more requirements. The momentum can be difficult to get going, and the learning curve takes a bit of effort to overcome. Yet, a properly managed requirements documentation phase will invariably lead to a fast-paced discovery process in which countless details are revealed, considered, and handled before any development begins. Of course, this approach has many benefits:

• Corrections and changes are made prior to programming, when they are still easy and have less of an impact on the project budget and timeline.
• Developers are confronted by fewer on-the-fly changes, which increases morale and code quality.
• Clients get a chance to ask questions without impacting the developers, or risking issues related to change orders.

To make the most of the specifications documents, you'll want to create a workflow scenario where the document gets passed from person to person, with one individual as the lead document manager and owner of the document. At first, you'll need to do most of the work yourself, since most clients won't know where to begin with this kind of process. However, you'll soon find that, by reading the document, the client begins to think about details and provide you with useful information and insight into their true objectives.

For example, I recently created a requirements document for a Web-based application intended to automate various functions in a county health facility in California. For the first 10 days or so, I plugged away at the requirements document on my own, adding as much information and detail as I could. Once the document reached about 35 pages, I began getting the occasional question from the client, usually related to client-friendly issues such as click-paths or cosmetics.

One day, the client called and asked me why there was a requirement that said the 'new patient' form must have a button entitled 'Insurance Information', and why the button would lead to an 'add insurance information' form when clicked. I explained to the client that I had been told that each client would have insurance information, and that this information was to be captured.

Soon, the client clarified the requirement and I learned that 95% of the patients defaulted to a particular type of insurance, and the only patients about whom insurance information really needed to be captured were patients who were referred by a particular county agency.

Thus, a decision was made that if the user entered a certain value into the 'referring agency' field earlier on that page, the insurance form would appear as a pop-up. Wondering how many instances there were of this type of dependency, I asked the client to consider what other pages also needed to behave certain ways under certain circumstances. The next day, we got a list of about 10 similar requirements, some of which were quite complex and would have been extremely unpleasant for the programmers to repair if they'd been built incorrectly.

A single question about a small detail resulted in a useful dialog that saved many hours of development, by allowing my team to do it right the first time.

With time and practice, you can educate your client to be mindful and aware of form validation, pagination, field length, navigation and other details that are typically overlooked. It is up to you to set the example, but there is much to be gained by 'coaching' your client to participate more effectively. Once you've established some momentum around the document, and all project stakeholders are contributing, simply continue until the progress drops off, then stop. The point of diminishing returns comes abruptly, and you risk fatiguing your client if you force them to participate in documentation beyond that point.

The Pain of SiteMaps

It is my opinion that sitemaps are bad. That's right -- just plain bad.

I'm not just saying that they're inferior to wireframe documents (described in the next section), or that they don't accomplish much. I'm saying that they are actually bad for projects, are misleading, and usually cause wasted time and confusion.

Sitemaps provide a means of diagramming every page in a Website for planning purposes. This seems like a good idea but, in practice, sitemaps always fall short of that goal, and usually serve no purpose other than to give the client an impressive diagram to approve.

Sitemaps attempt to detail all pages in a site, approximate navigation and page flow, and to represent this information visually. However, if you take the average sitemap and try to draw a line between every pair of linked pages, you'll soon have an illegible spider web of lines and boxes. As most Websites have persistent navigation (and even secondary navigation, like footers and sidebars) on every page, the lines between the boxes are generally arbitrary, and only serve to show a general relationship between pages within a section -- something we intuitively know already. An approved sitemap causes people to think they have documented all the navigational details and page flows when in fact there are usually many pages and features left to discuss once the sitemap is approved.

Sitemaps also completely fail to capture information related to dynamic pages, and usually omit things like feedback/response pages, etc. Some pages behave differently depending on whether a user is logged in -- another feature that's rarely mentioned on the average sitemap. In addition, most sitemap authors attempt to squeeze an entire sitemap on a single page, resulting in a nice-looking but rather useless document.

Even basic information such as 'when you click here, this happens' is completely lost in the sitemap, which tends to be too cluttered to allow the addition of callouts or other notes to the pages. (A callout is a small text note with a line pointing to the element that the note refers to.) Understandably, the sitemap is not intended to provide incredible detail about anything, but the only thing it seems to provide is a bunch of boxes with the names of the individual pages typed in.

So, what's better than the sitemap? The wireframe, of course!

The Joy of Wireframes

Used correctly, wireframes can be one of the most effective tools in a Web developer's arsenal of project management techniques. Simple, though tedious to make, wireframes might seem like a painfully laborious exercise in documenting the obvious. However, you might soon find that a 10-page wireframe document reveals informational disconnects between your project team and your client, and provides a convenient documentation structure for capturing, discussing, and clarifying the matter at hand.

What is a Wireframe?

The wireframe document is a simple diagram created in Microsoft Visio, or Inspiration (for Mac users), or by hand, which shows the functional elements contained on a Web page but completely disregards the copy, graphics, fonts, colors, layout, and other aesthetic elements.

The objective of the wireframe is to document and clarify what elements (headers, footers, forms, buttons, ads, copy blocks, search boxes, etc.) will be included on a page, and how the page will behave when clicked ('clicking here will re-sort the results by date') so that the project team and the client can effectively communicate the specific requirements of a Website.