Designing Requirements Documentation

About 14 months ago, [a large mobile operator] came to us with an interesting project for mobile handset UI. There was practically no mandate to design the interaction itself, in any way. Instead, we were asked to take a muddled mess of poorly-updated Word documents, a compliance spreadsheet branched from it a couple years before, and a pile of notes, and make... something, that would be a better specification for OEMs to implement the operator UI on their handsets.

All their handsets (first, featurephones, but various smartphones followed as secondary projects). It's not just paperwork, but a pretty big deal, and influences a lot of hardware, so many millions of users. And in that, it's actually a quite honorable design job. If there's a design, and it's good (or good enough) but is not being implemented correctly or consistently, then a key job for a UX person is to get it implemented, right, and well.

I for one take design seriously. Everything around the office, and even the office itself, are designed experiences. Poor proposals don't get us work, and poor specifications don't get our work implemented correctly. Designing documentation, even when just overhead, is ongoing and valid work I spend a lot of time on. See the mobile design elements, freely shared, for a hint how much we pay attention to this.

The openness of this specific request gave me great freedom to maneuver. We designed both a document and a whole new document format. And we took that "design" step pretty seriously. The first step was weeks of interviews. First with the operator – and with several teams from the operator. Then, with the OEMs. As an example, here are the people that we directly interviewed:

• Handset OEM product managers
• Handset OEM compliance managers
• Operator vendor managers
• Operator development managers
• Operator UXD interaction designers
• Operator UXD graphic designers
• Operator quality assurance staff

Remember, organizations are not monolithic, so teams from inside an organization may have totally different opinions or totally different ways of using a product. I knew this, which is why we set up so many interviews. And I was still surprised at how much variation we found, even with teams who work together every day.

For the OEMs, we sadly did not get access to all of them, nor to the document consumers directly. Like on a lot of B2B projects, there's politics and it can be hard to get to the right folks. But we got enough useful information by really prying and asking uncomfortable questions and absolutely promising not to share the direct answers with the operator. To encourage this sharing, there was no video record, just notes. And because of that, a backup note taker to make sure we got it all.

Then, we analyzed, and came up with some design principles. Which we had to combine with what the client team at the operator thought they wanted, and careful consideration of how each team perceived themselves. We didn't get far communicating changes to the overall process, strategy or organization. Though I got all excited about this, in retrospect that was dumb, or had to be approached very differently and more carefully.

So we dropped some of those issues (along with some great ideas for making it all a database) to focus on the print-style documentation and came up with these design objectives:

• Clarity – Remove ambiguity and the ability to interpret documentation in multiple ways.
• Consistency – Terminology and document style should be employed consistently for all requirements and documents.
• Extensibility – Use systems, such as permanent requirement numbering, that will not expire rapidly, and do not need to change as documents are added, removed, merged, or modified.
• Accuracy – Review for accuracy, but also design a process that encourages accurate documentation.
• Avoid duplication – Design a system of writing, organizing, and storing requirements that avoids or eliminates stating requirements in multiple locations, eliminating inconsistency due to out-of-synch updates.
• Reference – All references to other documents, other requirements and related tables, figures, or examples will be explicitly referenced in a consistent, repeatable, and discoverable manner.

Which is indeed derived from the research, but could also be guessed from heuristics if I had paid better attention to the many documents I have made, for many different types of implementation teams – although it was nice to have the proof in front of me when discussing with the client. A lot of the specification methodology was in fact already in my head from writing BRs, FRs, and deleveloping design documents over the years. And, as I have mentioned for some of these blog posts in the past, I just had to write it all down.

For example, every item is numbered. And the numbers are internally meaningless. We use a Google Spreadsheet which everyone on the Little Springs team has access to (this is not it, just a sample). You just increment that value in the shared spreadsheet by one, and type the number in the requirement spreadsheet. The outline-format (e.g. "Requirement 15.2.3.1") is fraught with peril, and violates a lot of permanence and repeatability needs. It took a while to get everyone on this, but it's fundamentally the right way to do it.

And once you have permanent, consistent numbers, you can do other useful things. Like have notes and figures that hang off the side. In the final spec they are tied with nice neat lines. But no matter what happens to format, you can't lose them because they carry that number. And... oh, dozens of other format and process tricks I won't burden you with. Here's what the final spec looked like:

This is a sanitized version with no references to the operator. The real one was delivered with their branding, because that's also a key to communications with the OEMs. It happens for a fair number of our clients. Again, the project is more important that we are.

We also spent a lot of time analyzing and re-writing the specs themselves. A totally consistent method of writing was developed. There's far too much to include here, but some samples from the "Guide for Writers of Requirements" (not distributed to the document consumers) include:

• Condition, Event, Result – Requirements should be written as full sentences, in the following format: Condition, Event, Result. Like this:
  From any text entry screen, pressing the [FUNCTION] key twice will "Lock" the key and afford the continuous entry of secondary keys (hereby referred to as "Function Lock").
  Here the condition is "from any text entry screen" the action is "pressing the key" and the result is all that about locking, and allowing continuous entry. Note that several preconditions, several actions, and/or several results may be expressed within a single requirement.
• Define, then Expand – Requirements are written in groups, where the title, any explanatory notes and (often) the first few requirements will define the group, or define the function or tool or set of behaviors the group is about. All the subsidiary requirements expand on this core definition with specific behaviors, processes, and display details.
• Free-Standing – Regardless of the grouping, each one should be free standing. The condition statement especially should set the full conditions. Never just say "on that screen..." or otherwise assume a context based on grouping with other requirements. Always give full names for each location, action, and item referenced.

And terms were standardized. "Handset" for example became the one and only term. Never "device," "phone" or anything else that strikes your fancy. Note the [Function] key reference in the sample above; square brackets mean a hardware button. These standardized terms and notations were then included in the introduction, with an explanation that the OEM implementation team could look up any term by simply searching for it.

We did a lot of card-sorting sorts of work. At once point we printed out each and every requirement. This was before we re-wrote them all and combined the dupes and errors, so we had around 9,000 little slips of paper. Which we stuck to walls in order to create categories and groups and sub-groups. Pretty much all categories from the previous document were discarded and rebuilt with this method. Which, in the interests of secrecy, we apparently did not photograph. Which makes me terribly sad now. It took up a pretty good percentage of the glass walls in the office at the time and was quite impressive.

And this covered the bulk of the work well. But even with re-structuring the document, it didn't hold together just perfectly. And, there were lots and lots of flow charts in the original operator documents. Like, almost 100 of them. Which really didn't do anything for me. No one else was bothered by it really, but like I said, we're designing a document and I didn't want the document to be just passable, workmanlike or good. As with anything I design, I wanted to take the opportunity to make something great. And here I sorta had the time to do so.

So, I began to focus on a systematic approach to diagramming with the hope of wrapping the flow charts back into the requirement text and making it all work together. I pulled a whiteboard over to my desk, scribbled boxes, and pondered things a lot. I also failed to take photos of this, so can only talk so much about the process.

Fundamentally, I realized that there wasn't that much going on in each section we'd created. I mean, the dialer shown in this sample (if you haven't noticed, click on the images to get a PDF of a few pages of this document) only consists of a dozen subsections, and a hundred and some odd requirements. If you go for that 2002 style of screenshots, depicting each and every state, it's dozens, or hundreds. Actually, I did some back-of-the-napkin math on this problem, and for some fairly small subset of information, it's actually like 200,000 variations.

No one is gonna draw that, much less maintain it. And no one can absorb this information and build a useful system from it. Which is a key issue with all specifications. Technical systems are so complex you can assume they are essentially infinitely, undefinably complex. So, you better come up with a better way. I solved this in two ways.

First, with modularity. I didn't explain them at the time, but in the gutter between the two columns in the spec page above, note those little drawings. They refer to these fundamental, reusable components that were pervasively applied. Many existed in principle, some we had to make up. And then we made all the drawings, in a specific style which you can find in the Mobile Design Elements document as "Mid-Level" diagrams. Because I couldn't come up with a better name.

These are shorthand for the basic module, which could be as simple as "a scrolling list" or even in-page widgets like a type of contact list entry. Any variations of the list fundamentals are covered in that spec point and don't need to be addressed when you talk about the address book. Most everything else is just data; the title of the page, what goes in each element. And soon you can define an entire chunk of the interface with a single drawing in a flow chart. (Oh, and note the little gray reference labels below the re-usable module above. Even that has components it refers to. Nest reusability for even greater efficiency of documentation and to encourage code reuse.)

So, I did. The flow chart above is as simplifed as it can be, but covers each and every path that can be taken. Really. And if you want more detail, that's what the bars at the top are for. They provide an easy way to find more information. Try it out. Look at that flow chart above. That very first box in the chart, "Dialer first entry" has a thick blue line which goes all the way up to a bar labeled "1280 Dialing a Voice Call." Scroll down in the document a few pages and you'll find a section (actually, a subsection) with the same title and number. And under that are a stack of requirements detailing how this function works.

Note that the 1280 bar links to the first three boxes. So, even though there are dozens of functions, they all collapse into these few states. The details are within these basic view states and don't need to be on the flow chart.

I did this exact thing for each section. Dozens of diagrams were reduced to about eight (I haven't counted lately, but it's not many) at the front of each major section, serving as a guide for those who like visuals, and as another way of viewing the data (a flow chart).

And, wrapping around to something I have always valued in my design documents, as a checkpoint that the design works. I think documentation should not just communicate the idea, but help the designer, whether it be UX or software or systems or database design. Making up these flow charts exposed a number of issues; impossible conditions or endless loops or undefined states. All of which we filled in.

And since it's all designed to be easy to understand (the client has essentially a more explicit version of this essay), anyone revising it in the future can use this, even if they don't know that's the intent. When they add a feature, they hopefully go back and add it to the flow chart and if it doesn't fit in there... well they ought to notice that and work it all out. A self-correcting system.

I can't ask a lot more of any of my work than that it do good, help someone, and last for a reasonable amount of time.

In case you want even more about this, there's a follow-on about working with requirements documentation and I am now presenting a session on basically this topic at the Design for Mobile 2010 conference>. Even if you don't want to see me, there's plenty more to learn about mobile design, technology, strategy, research and implementation. Still some space available, so join us in Chicago next month.