In my blog post about avoiding reviewer fatigue, one of the things I mentioned was following all of the guidelines for creating a consumable deliverable. Deliverables may take many forms—a word document with use cases, a visio document of models, an excel spreadsheet of wonderful information, etc. Regardless of the form, the deliverable needs to be consumable. By consumable I mean:
- I can easily understand the entire contents of the deliverable. I once worked with a guy who said that requirements documents should tell a story. I agree with that, your reader should be able to quickly orient to what they are reading and then receive information in a logical progression.
- I can use the deliverable as a reference. I can quickly find information I am looking for within the deliverable, without having to read the entire thing.
I’ve found some deliverables are easier to consume than others, and in that vein I’m going to provide a list of tips to make your deliverables more consumable. A lot this is just common sense that we loose track of when we’re in crunch mode.
- Provide a good table of contents. Have you ever tried to master the information in a 10, 20 or 30 tab spreadsheet or visio file without a table of contents? I see this all of the time, and I always wonder why the author doesn’t want me to be able to use the information. Let me know what I am looking at. Help find something quickly when I need to. The table of contents of a deliverable is a meta-model which provides an abstraction of what I am about to consume. If your table of contents doesn’t reflect information organized using the rule of 7 +/- 2, then you probably haven’t organized the information well.
- Put the table of contents first. This is a corollary to the rule above. When I open a deliverable, the first thing question I ask is “what is here”? A table of contents up front tells me that. A table of contents at the end or buried behind little-used information is less usable than one that is up front.
- Unless it is critical to understanding what follows, put seldom-used information at the end of the deliverable. We’re back to one of my pet peeves–revision History and Approvals that are at the very beginning of the document. Most consumers of the document don’t care. Those who do care will find them. Why does everybody have to page through them? I’m one of those freaks who actually does fill out revision history; this section can get quite long. I hate having to wade through it to get to the real information. But, I love having it when someone asks “when did we make that change?”
- Provide a meaningful introduction. If your table of contents is good enough, it is your introduction. Otherwise, explain the context for the deliverable. What does the reader need to know to read the rest of the deliverable?
- Use requirements models. If your deliverable is a set of requirements, use BDDs, Process Flows, Use Cases, etc. Providing context for what the reviewer is reading is invaluable.
- Organize your information. Here’s where I have to admit it: my short-term memory is lousy. Consequently, I’m always organizing information so that I don’t have to memorize it and I can easily find it. I’ve found that other people react very positively to organized information. Organization is part of letting your deliverable’s story unfold. If you organize right, the story flows. If you don’t, the story if very hard to read. Do you have a lot of requirements statements? Organize them by mapping them to process flow steps or use case steps.
- Use readable fonts. I tried to read a set of process flows once that used a 6 point font. The negative frame of mind brought about by the small font was very detrimental to reading the information.
- Know how your deliverable is going to be presented to the reviewer; consider how the deliverable will look when it opens. This is one a lot of people don’t do. Have you ever opened a Visio file and all you can see is a few process steps on the middle tab? Save the file with the cursor on the first tab (or, the one you want viewed first) and make sure each diagram is visible on the page. How about Excel? Have you opened a file with the cursor in the middle of a spreadsheet and not realized there was more information? Was valuable information hidden, and you didn’t realize it? Before you save a file, think about what you want the reader to see when it is opened.
- Think about how the deliverable will be used. A lot of people still like to read hard copy. Unless you know your deliverable will not be printed, it should be hard-copy friendly. The means setting it up for printing before you send it out using page numbers, headings, etc. It also means providing useful cross references within a document. Ever read a word document that has a cross reference along the lines of “see the information here.” The here link is great when you’re interacting with the document, but useless on hard copy. I like cross-references to include section numbers, names, and page numbers. They allow someone reading a hard copy to find the cross-reference.
I’m sure some of you have more tips. Please share.