Influencing the Requirements Process - Designing Documentation, Part 2

Specifications are hard. There are a lot of conflicting needs, and the complexity of the documents might be more severe than the product you are specifying. Aside from designing products or interactions or interfaces, I spend a lot of time designing the documents themselves. A happy ending to this sort of process is detailed in last week's post on Designing Requirements Documentation.

Which might bring up the question: What type of specification? Design documentation, which is most of what we do (well, by hours – most actual documents by count are proposals and emails and so forth) took a long time to settle on, but it has evolved into something pretty specific and which works very well to communicate to everyone on the entire project team. There have been several evolutions, many mandated by technology alone; I used to do everything as a single sheet which functioned as sitemap and flowchart and detailed page/state layout. But when I had to work with more remote teams getting 36" x 10' pieces of paper to them was more difficult and had to change to something else.

But complete technical specifications are still something else. There are also content specifications, style guides, and lots of other documents. But today let's talk about the general technical specification, that developers use to build or modify software or presentational code to meet your design needs. Integration of technical specs with design has always been an issue. I've spent a lot of time messing with my deliverables to make them comply, or revising them to be pasted into the appendix of an IT specification. All of which is fairly unsatisfying and never helps much.

It is also important to believe that design documentation is good, important, valid work. We spend a lot of time buried in IT process, and I have to fight even people here at Little Springs to make them believe that our work and our method of work is valid. Sure, you can use IT requirements documents to do your work, but that's not their intent, and there are better ways to do it.

After a lot of work imposing myself and my team into the development process with our own documentation, way back around 2002 – while working at Sprint, I got to work my design documentation directly into the technical specification. At the time, Sprint IT used something called Application Design Documents, and I was able to persuade them that the UX team could do the best, most efficient job of making some of the document.

Note that the text and tables are in the IT format, specifying the behavior of each widget in a specific manner. And the screenshots (I prefer other methods, but this is what they could handle at the time) are placed in a process-compliant manner, but there are just about 20 times as many as usual. I also did a lot of the writing, or at least editing, of the specifications, so when it was done both the IT analyst and the whole UX team agreed on the behavior of each and every feature.

This product, both by design and implementation, was a high-water mark in ease of use in my career. Web-initiated SMS with millions of uses a day, without a help system and hardly any error messages, with impossible uptimes and no measurable customer complaints. Almost unheard of for a mobile telecom operator, at least in the US. And although it took forever to create the document, some of this was simply getting everyone involved used to the new process, and we saved a lot of time correcting errors and explaining stuff in development.

But then that dream died. After a few months of work, a big fire-everyone-for-IT-outsourcing binge left disappointingly few software designers and analysts in house. I had to start all my relationships over and reconsider how all deliverables would work with random, far-away teams using them. So for the next few years I made do by improving my design documents, communicating with project teams as much as possible, and actually writing requirement documents when I could.

Writing requirements

Which became a key task I tried to accomplish. If the UX team got engaged early enough (which is always a problem) I pushed to review and approve the requirements. Then I found out no one wants to write them, so simply volunteering gave the UX team lots of additional authority.

A key reason I like working on requirements is that they are often poorly done. For example, Business Requirements and Functional Requirements are too often conflated. A BR document is very, very high level. It contains the goals of the project, and rarely more than a couple dozen, or that's a sign you either wrote them wrong or the project is too big to be completed. Some Business Requirements you might read are:

• System shall have the ability to allow user to enter a street address and geocode it to a dynamic map displaying coverage and signal strength.
• System shall have the ability to drill down from a national map perspective if no address on file for user (i.e. in-front of log-in).
• System shall have the ability to allow user to enter only a ZIP code and geocode it to a displayed map.
• System shall have the ability to allow user to enter an intersection and geocode it to a displayed map.
• System shall have the ability to allow user to enter a City/State combination and geocode it to a displayed map.
• Etc.

But this is dead wrong. System? And so very many. That's a set of Functional Requirements, and not a well-written set at that. But all is not lost. Assuming that the marketing and product people like these, you can redo them as actual requirements. A typical, well-written Business Requirement could read:

• Allow customers to find coverage for a specific area in multiple ways: by entering a general location, a specific street address, an intersection, two locations, etc.

And this covers all those bad requirements above, and then some. Cases you don't think of at the beginning of the project are still in scope. A half dozen more like this and you have a project.

Functional requirements

A Functional Requirement on the other hand provides specifics of technical, logical, or presentational behavior. These are also boring, so often don't get enough attention. Oh, they have to be written to proceed through the IT process, but no one wants to do it, so they get poorly written. If you want to make sure the product gets built right, and that the implementation teams are doing what you designed, just insert yourself in the process.

Good Functional Requirements look like this:

FR-40 From within the Wired Web unified messaging access portal, a function will be provided for customers to move SMS messages between folders, (e.g., Inbox, Outbox, Spam).

Better written Functional Requirements help a lot. Some notes about requirement writing were in the earlier blog entry, so I won't repeat them here. But they better not all start "System shall" or "Ability to." Even if it's nerdy, academic, and technical, with otherwise annoying neutral-voice characteristics, use good english, first and foremost. The above requirement is written the way I like them all to be. First, the condition or state From within. Then, who can do it, here the customer, but the system may automatically do things at certain times or when certain conditions occur. And then, what happens. Pretty generally. An example of the folders are given, but there's not a requirement for each folder, and a comprehensive list is not given.

Not just because this would be cumbersome, but because it would be wrong. Remember, there are other documents and other requirements. The structure of the folders here is likely described in some architectural specification. So as part of this writing, be sure to understand the scope of the document, and how it works with the many other documents that are part of the IT process upon which you have imposed yourself.

The product is more important than you are

And after all that, it is a bit thankless. Your name will probably not be on the document as an author, and everyone will credit the analyst, who may not credit you. That's fine. Often, it's preferable, since UX is viewed with dark suspicion by parts of the organization.

Even as a vendor, we pretty often deliver work in someone else's template (or, have to create one that looks like the client's brand).

Getting the product right is most important; work on how your team is perceived later. Which is probably a good topic for another post in the future.

While I won't be hosting a process workshop at this year's Design for Mobile conference, 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.

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.