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

Consistent Nomenclature

If the documentation is to be successful, everyone must speak the same language. This includes the client, the developers, and anyone else involved in the project. When writing requirements, you can create naming conventions and nomenclature that can reduce confusion for the entire duration of the project. This requires that you establish naming conventions early in the project, and require everyone involved to use them as well.

For example, let's say we're developing an online store. During the early discussions, everyone kept referring to the 'cart', the 'store', the 'product pages', 'the store page', 'the front page', the 'product closeup page', etc. Although we usually know what is being referred to, a surprising amount of clarity can be gained by establishing naming conventions for the pages. You can accomplish that by using consistent nomenclature in our documentation, such as:

• Product Category Page: Shows 3 rows of 5 product thumbnails with prices below, limited to a single category, Reached by clicking a category in the category list in the left-side nav.
• Product Detail Page: Shows a single product, with detailed attributes.
• Search Results Page: Displays paginated results of a search, following the format established by the Product Category Page.
• Contact Feedback Page: Displays results of a feedback form after one is submitted by a user on the Feedback Form Page

By writing your requirements in a concise, distinct format, you'll soon have the entire project team using your chosen nomenclature and communicating more effectively. This avoids ambiguity problems, such as the client referring to 'the pages that come after you click on the search page but there aren't any results', etc.

Effective and consistent nomenclature is an excellent practice – it's one of the pillars of great documentation and successful project management. Always try to name and identify everything early on, so that the other project members will be able to refer to the pages by their exact names as the planning unfolds.

Numbers and Dots

The most accessible and simple format for capturing requirements is via Microsoft Word, or a competing product such as OpenOffice or Star. Although many tools and systems have been specially designed for requirements gathering, Word is an excellent option for project managers who are just starting with formal documentation and aren't ready to invest in custom tools.

The Word feature you'll be using is the 'Styles' feature, which allows the author to establish styles, use the outline mode, and show numbering on screen. Make an outline, then assign the style 'Heading 1' to the top level, 'Heading 2' to the second level, and so on. This produces an easily-read and highly flexible document, with a format that follows a strict numeric organizational scheme, like this:

1. Merchant Account Integration
  1.1 Authorize.net must be integrated with OSCommerce.
    1.1.1 Vendor must work with John Doe at authorize.net to certify that the
    installation is performed correctly.
    1.1.2 Integration must be completed before August 21, 2003
  1.2 Two-way integration must provide information about charge/authorization results
    from within the admin screen
    1.2.1 sub-requirement, etc.

Add as many levels as you need, and rearrange whenever you see fit. Additional benefits of Microsoft Word include the automatic generation of tables of contents, indexes, and other client-friendly cosmetic effects.

To learn how to use these techniques, use the built-in help in Microsoft Word to find information about the following features:

• Styles, especially Header 1, Header 2, Header 3
• Document Map
• Outline Mode
• Bullets and Numbering
• Table of Contents

More Is More

When I write requirements, I always try to follow 2 self-inflicted rules:

1. If you can provide more detail, you should -- that is, unless the details are intuitive to all concerned project members, irrelevant, ill-defined, or unlikely to have any benefit to anyone. Even if you understand the details, it's still wise to record them in the document.


2. Always keep your requirements organized so that you can refer to other sections easily, eliminating the need to repeat yourself. Not unlike SSI/includes in Web programming, a well organized document allows each section to refer to any other section to address global details such as navigation and style.

Taking the online store as an example, let's say you are capturing an interface requirement and section 3.x of the functional specifications document is being used to capture interface requirements. You might start with a basic requirement such as:

3.3 The Product Detail Page will show a 'zoom in' button which, when clicked, will show an enlarged version of the product photo.

This is a perfectly legitimate requirement, and follows the traditional 'a must do b' format of well written requirements. However, there is much more to say about this feature, as evidenced in the next example:

3.3 The Product Detail Page will show a 'zoom in' button which, when clicked, will show an enlarged version of the product photo.
  3.3.1 The zoom image will be displayed via DHTML, and will appear in a set position on the user's screen.
  3.3.2 Some products don't have zoom images. For these products, the 'zoom in' button will be grayed out on the product detail page.
  3.3.3 The DHTML browser compatibility level will be MSIE/NS 4+. Users whose browsers do not meet the specifications will not see the zoom images.

The expanded requirement is becoming much more useful. However, this feature raises the question, 'How does the zoom image get in there?' We'll add to a different section of the document the following entry, which captures requirements for the administrative interface.

10.1.2 Zoom images can be uploaded from the Product Administration Page. If a product has no zoom image, a dialog box will appear to confirm 'Are you sure you want to add this product with no zoom image?" prior to saving the product record.

If the administrators are allowed to upload the zoom image, they'll need to know what type/format needs to be uploaded for proper display. Let's add one more requirement to clarify this (notice that this is a sub-requirement of the above requirement 10.1.2, because it only relates to that requirement):

1. Uploaded images must be jpeg format, less than 20k, and exactly 400x350 pixels in dimension.


2. The admin interface will reject any zoom images that don't meet the above spec by displaying an error message including the specification that wasn't met by the image.

Okay, the requirement is beginning to become clearer now. But, clear requirements have a tendency to create more questions. For example, 'How does the user return to the non-zoom image once it's displayed?' We'll add yet another requirement to make sure that the developers build it right the first time:

3.3.4 While the zoom image is being displayed, the original 'zoom in' button will change into a 'zoom out' button so that the user can return to the original view.

And, just for usability purposes:

3.3.4.1 Clicking on the zoom image will also return the user to the ordinary view.

This process of each requirement illuminating the need for more requirements is typical, and is a sign of good momentum in the documentation process. Even in the simple example above, there are many more considerations that could be addressed, such as:

• Can zoom images be added to existing products? How?
• How are zoom images stored on the server? What naming convention is used?
• What server-side process is used to evaluate the uploaded images?
• Does the zoom image show up in the product preview page?

Once you adopt the mentality of capturing and expanding upon requirements as we have above, you'll find that lots of little details get documented that would otherwise have resulted in phone calls, repeated work, or other time-consuming productivity killers.

If the question, 'How do you get back to the main product image?' hadn't been documented above, the client might have called months later asking the very same question. This could occupy 5 minutes of your time on the phone, plus 5 minutes communicating to your developer about how to fix the feature, plus the additional 15 minutes it might take for the developer to make the fix. That little detail cost you 25 minutes of time, and if there were only 20 similar incidents, you'll have wasted 8 hours of time to avoid 30 minutes of documentation.

Meaningful Use Cases

'Use cases' are a proven means of capturing the essential paradigm of an application's desired functionality. Although use cases can be considered functional requirements, they are typically captured in a special part of the document and corresponded to the main requirements using a numbering scheme. Other approaches involve the creation of a special use case document, or writing them right alongside the main requirements.

Use cases are simply a different way of answering the, 'What does the application do?' question, by answering the complimentary question, 'What does someone do with the application?' In other words, use cases offer an alternative approach to capturing requirements by allowing the author to write them from the perspective of an actual user.

Some requirements are best captured in the standard format of, 'the application must do x and y.' while others are much easier to describe through use cases. In general, requirements that are part of a long, complex process that spans multiple pages are good candidates for a use case. Take, for example, the following example of a use case that describes a content management tool at a high level:

1.4.4 Bob, the article writer, logs into the system and clicks the 'submit article' button. He uploads his work and fills out a short form detailing the article and its header information. The next day, Bob's editor finds an email notification in his inbox telling him that a new submission is waiting for him. He logs into the system and is shown an alert that Bob's article is waiting for approval. The editor reviews the article, and decides it needs to go back to Bob for revision. He adds several notes to the online form, and clicks the 'return to author' button. Bob is notified. He later logs in to read the editor's notes, fixes the article and resubmits it. This time, the editor logs in, reviews the article, and approves it for publication. The system automatically sends the article to the publishing department (see use case 1.22.3)

Use cases work well to describe a long, complex process like the above sequence of events. It would be simple to write sub-cases to show how the flow might work under various approval sequences.

Use cases don't work well when you're describing simple things that could be captured in a standard requirements format. Let's take the 'zoom image' example and see how it might work as a use case:

Steve, a potential customer surfing the ecommerce site, is viewing a product on a product detail page. He sees the 'zoom in' button and clicks it, which causes the main image to change into the zoomed image. The button changes also to provide way for him to return to the main image.

This use case is helpful, but is ambiguous and lacks conciseness when compared to the regular requirement we looked at in the previous section. Use cases and requirements need to work together, and each feature should be evaluated to determine the best documentation approach for that specific detail.

Test Cases

Yet another handy information type, test cases answer the question, 'How can I prove that this works?' The objective of a test case (also known as a test script) is to provide simple sequences that can be provided to a non-developer and reproduced to prove that the application actually works.

Test cases are written to give the testers some instructions about what to do. In the online store example, a simple but effective test case might read something like this:

Log in to the admin section as admin/admin. Add a product with no zoom image. Log out and visit the store pages and confirm that the new product is there and is correctly displayed. Confirm that the zoom image is greyed out. Return to the admin section as admin/admin and attempt to upload an incorrectly sized image as the zoom image for that product. Confirm that the system refuses to accept the image and gives a meaningful error message. Add a correctly sized image, then logout to confirm that the image is properly displayed on the product detail page for that product.

If you think that test cases aren't much different from use cases, you're absolutely right. In fact, test cases are really just functional requirements in reverse -- changing the, 'Application must do x and y' format into a, 'Does the application do x and y?' format. The time you invest in writing good requirements can make it much easier to generate test cases, which we'll discuss next.