Pictures can convey messages much more powerfully than words.  In a recent discussion about writing whitepapers, I suggested combining the idea-creation advice from Made To Stick with the image-creation advice from Back of The Napkin.  Check out this article to see some concrete examples.

Made To Stick

Paul Young, product manager and author of Product Beautiful,  sent out a tweet the other day asking:

Anyone have any “best practices” for whitepaper development? E.g. most whitepapers I read are stilted, I want to make something compelling.

Tweet, on twitter

I suggested combining the ideas from Made to Stick and Back of the Napkin to create a compelling whitepaper.  Stephanie Tilton then replied with a link to a good article she wrote showing how to apply the ideas from Made to Stick to writing whitepapers.

The book, Made To Stick: Why Some Ideas Survive and Others Die, written by Chip Heath and Dan Heath, has some very powerful ideas for communicating ideas.  Stephanie sums them up nicely in her article:

• Simple
• Unexpected
• Concrete
• Credible
• Emotional
• Stories

Stephanie Tilton, How to Craft Whitepapers that Stick in People’s Minds

Check it out, she goes into more detail, with examples and insights about why they work.  What about the Back of the Napkin ideas?  That’s what this article covers.

Back of the Napkin

I remember feeling like I’d been hit in my frontal cortex with a frying pan at Product Camp Austin (Winter 2009), when I first saw a visualization created by Sunni Brown of Brightspot for one of the presentations.  I remembered hearing about Back of the Napkin: Solving Problems and Selling Ideas with Pictures, by Dan Roam, and immediately ordered it from Amazon.  This is actually the current book for the Smarter Product Managers book club.

Applying these visualization techniques is extremely compelling for sharing ideas.

There is a ton of science behind why (and how) visual presentation of ideas (pictures) works so well.  Dan Roam does a fantastic job of making this approachable and actionable – an excellent book.

Getting back to the conversation…

How to Put Pictures in your Whitepaper

The rest of this article is showing some example images, in Back of the Napkin style, that support the ideas from Made to Stick, as you would include them in a whitepaper.

Imagine you’re writing a whitepaper about requirements elicitation.  There are a lot of important topics you could cover, but to stay aligned with the simple message from Made to Stick, you will want to focus on one idea (for each whitepaper, as Stephanie explains in her article).

User representatives are often offered to business analysts as a “convenient” source of requirements – the actual users are too busy, too valuable, or too easily distracted/upset/encouraged by conversations about the future.  This idea is both bad and pervasive.  You want your whitepaper to convey emotionally why this is bad.  You need something concrete, and maybe you want to tell a story.  Consider this image:

This is poorly drawn (but that’s ok!), but it establishes the metaphor that inserting user representatives into the elicitation process is like playing the telephone game.  The message (user goals) gets lost between the users and the business analyst.  It also points out that the conversation between users and analysts is what makes good requirements elication, well, good (ref. the smiley faces in the drawing if you’re not sure).

Designing for “Everyone” is a Bad Idea

One challenge for product managers is determining which features to include in their product roadmap.  Industry analysts, and sometimes buyers, have been known to use checklists to pre-screen or select products.  That may be true, but using a checklist to prioritize your product development is a bad idea, because you end up creating a product that doesn’t thrill any particular users, and just makes analysts happy.

The quick mock-up of a Consumer Reports style checklist shows a comparison of your product against the competition’s product.  With six features (A through F), it appears that your product is better.  [Here's an article comparing elicitation techniques, with a real consumer-reports-style checklist and an explanation of how to read it.]  You have six “half-circles” which looks to be “better” than two “full circles.”  Therein lies the danger.

Any individual user cares about two or three of those features (capabilities), not all six of them.  Will that user prefer your product or the competition’s product?

That user is thrilled to use your competition’s product, because it does what that user cares about, really well.  Your product is half-baked. Happy analyst, missing user (for you).

Increasing Distribution Channels Decreases Sales

Another key idea from Made to Stick is the notion of presenting the unexpected.  The authors point out that you need to demonstrate an idea that is at odds with the reader’s concept of reality – breaking it – and then rebuild the reader’s sense of reality around your new idea.  That’s where the unexpected comes in.

Consider that you are selling a product into a crowded market, with many places that customers could buy your product.  You do your inital launch, selling through one sales channel.  Someone proposes adding other channels – hey, more is better, right?

How do you prevent this Benedict Arnold from killing your company with what looks to be a great idea?  How about getting people’s attention with this “violation of common sense”:

That will get people’s attention.  What the Heath brothers point out is that to establish credibility with this unexpected visual, you have to rebuild people’s perspective.  You could do that with the following:

Since each store (channel) has a best-sellers list, like the Billboard charts for music, you want to make sure you’re at the top of the list.  Most downloaded is a common metric for software available on shareware and freeware sites.  If people can get your product anywhere they happen to be, it will dillute your rankings at every store.  By targeting your marketing and making your product available at one store, you will get more traffic (at that store) than you otherwise would.  Then new potential customers will be more likely to discover your product because it is at the top of the list.

Climate Change

I touched on credibility in the last example.  As Stephanie points out in her article, the Made to Stick authors were talking more about data than visceral understanding.  The first thought that popped into my head was the effectiveness of Al Gore’s data in his An Inconvenient Truth book (and presentation and movie).  He demonstrates that there is a correlation (and implies that there is a causal effect) between the average temperatures on earth and carbon dioxide levels.

Pretty powerful message.

Conclusion

Pictures like the ones above, drawn as Dan Roam suggests in Back of the Napkin can make the ideas you present in your whitepaper really memorable.  Use the Heath brothers’ approach from Made to Stick in crafting your message, and fold it into your whitepaper as Stephanie suggests.

The result is a compelling and memorable white paper, just like Paul always wanted.

An effective status report is one that

• Instantly conveys the state of the project.
• Creates a minimum of overhead for the project team.
• Gets you help when you need it, and latitude when you don’t.
• Is fun / energizing to the author and the readers.

An effective status report is not a myth, it is actually easy to achieve.

Goals of a Status Report

You do not create a status report because someone told you to create them.  You create a status report only when it benefits the project.  There are three effective uses of a status report:

1. Get help (escalating) when you need help.
2. Keep stakeholders in the loop so there are no surprises.
3. Get visibility for the accomplishments of the people on your team.

Problems of a Status Report

There are also potential downsides of creating status reports.  This doesn’t mean you should avoid creating a status report.  It means you should avoid status report mistakes.

1. A bad status report takes a lot of energy (and time) to write, making it expensive.
2. A bad status report is difficult to read, causing it to fail to communicate.
3. A bad status report covers up problems or cries “Wolf!” when things are under control.

Elements of an Effective Status Report

The following is one example of an effective status report format.  Other formats can work.  This one does.  We’ve been using it for months on multiple projects, with great success.  On one of our projects, the first status report in this format was forwarded around by the project sponsor for people to “check this out!”  Ever hear of that happening to one of your status reports before?  In a good way?

There are five components in this status report format.

1. The scannable forecast.
2. Last week’s accomplishments.
3. This week’s planned accomplishments.
4. Issues and resolutions.
5. The legend.

The Legend

Normally, we run through a list in order.  In this case, we will show the last section first.  The legend explains how to read the first section, the scannable forecast.

You can define any number of different statuses for a project.  “Red, Yellow, Green” is the most common.  A couple years ago, we proposed this metaphor for status reporting:

A great way to do this is with a stoplight metaphor (at least in the US, where green = go, yellow = caution, red = stop). We can provide a little color in our reports to make the status details and rollup easy to scan. When someone is the audience of a status report, its because the reader needs to know what is going on, but isn’t involved – and likely is reading status reports from other teams. We need to present a document that gives a quick visual that guides the reader to pay attention to the most critical elements.

• Red. Immediate action (by the reader) is required to fix this.
• Yellow. We’re at risk of failing to meet expectations. There’s a plan in place, but we thought you should know. Want to know more?
• Green. Meeting or exceeding the plan. No need to spend cycles on this one.

[Update 28 Apr 2007: We have a much improved metaphor for tracking project status - weather forecasting.]

It works, but it isn’t great.  You’ve all seen it, because it is adequate.  However, using red, yellow, and green to provide a scannable status can be confusing – even if your readers aren’t colorblind.  Does red mean the project is delayed?  Yellow usually means a project is at risk.  But is it “at risk, help is needed” or “at risk, FYI, help is not needed.”  That’s part of why we recommended the weather forecasting metaphor.  Thanks again to Johanna Rothman for originally sharing the idea.

The Scannable Forecast

When you look at the above, even without knowing any details  you know:

1. The project is in worse shape this week than it was last week.
2. The project will get worse before it gets better.
3. The team has it under control, today, but might need help next week.

Last Week’s Accomplishments

The bulleted list is extremely effective for scannable details.  The secret – use three to five bullets.  More bullets means you’re sharing too much, and fewer than three is not enough.  You’re reporting to a project sponsor who has placed trust in you to manage the details.  Your sponsor, when things are sunny may not even read the details, just relying on you to say “everything is great.”  The only time that you need to share more details is when things are stormy.  And those details (1) will come up in the issues section, and (2) will come up in conversation.

When someone on your team does something noteworthy, dedicate one of your bullets to that accomplishment.  If you have a dozen of these, then refine your definition of noteworthy.  You should already be providing feedback to your team about their work.  Noteworthy accomplishments should be broadcast up the chain.  Its a reward for their hard work.  Don’t under-report, and don’t over-report.  The people who consistently do great things will begin to get a positive reputation where it counts.  As a bonus, you will get acknowledgment for being a good manager.

This Week’s Planned Accomplishments

This is what you intend to do in the next week.  When your project sponsor does want to get a little more insight, perhaps to make sure that she believes that you will resolve things, she will read these details.  Again – a three to five item bulleted list is appropriate.

Issues And Resolutions

You report issues when you are (or anticipate being) cloudy or stormy.  You don’t waste your sponsor’s time on trivial issues that you can resolve on your own.  These are issues that either definitely require escalation, or may require escalation.  Again, you’re working a three to five item list.  On your project, you will potentially manage ten times as many risks, and you could track them in a spreadsheet, etc.  Those are the issues you are working.  These are the issues you need help to resolve.  And only the issues you need help to resolve.

Note that this isn’t just an issues section – it is issues and resolutions.  When you inform a stakeholder that you need help with a problem, the first thing you need to do is propose a solution.  Imagine the following exchange:

“I need help” – “What do you need?” – “I need you to ….”

Much better than

“I need help” – “What do you need?” – “I don’t know.  I need help determining what I need.” – “I know what you need, you need help updating your resume.”

For every issue, propose a solution.

The issue section is also not meant to be a standalone document.  Here’s another bad exchange:

“I need help” – a couple days go by – “I solved your problem for you.  And I’m replacing you with someone I can rely on.”

Your project sponsor shouldn’t have to ask what you need her to do.  She should, however, want to know why you think the proposed solution is best – and you should talk to her about it, not present a rationale within your status report.

Practical Experience

I’ve created many status reports using this format.  They take anywhere from 15 minutes to 45 minutes, almost always under 30 minutes.  When they did take any significant time, almost all of that time was spent in thinking about the content to report in the “Planned Accomplishments” section.  And that is not time that I spent writing a status report – it is time I spent planning, on those occasions where I procrastinated in my planning, and the writing of the status report triggered a brief planning exercise.

Brevity in a report goes a long way.  As does regular face-to-face (or at least phone-to-phone) conversation.  A status report alone better not be the only way you communicate.  It should be a light-weight artifact that (1) starts the important conversations, (2) preempts the time-wasting conversations, and (3) provides an archive that you can review later, to see the full arc of the project, gain insights, and run your next project even more effectively.

Having trouble working through complex concepts?  Struggling to get a “simple” message across?  As human beings, we are all pre-wired to absorb visual communication.  You should take advantage of that to give yourself an edge when it comes to communicating.

Thinking in Pictures

Guy Kawasaki did an interview last week with Dan Roam, author of The Back of the Napkin: Solving Problems and Selling Ideas with Pictures.  There are eleven good questions with detailed answers, so it is definitely worth a read.

Whenever we hear a pitch or evaluate an idea, we go back to first principles and try and understand why something might work.  If we believe the explanation of why something might work, we’re much more open to the possibility that it will work.  Here’s part of Dan’s answer to Guy’s question about how and why using visuals to communicate can be effective.

Recent breakthroughs in vision science have indicated that there are multiple “vision pathways” along which the signals from our eyes travel into and through our brains. Each pathway keys off different visual cues in the environment–one pathway looking to identify the objects around us, another understanding where they are, another determining how many there are, another watching for changes over time, etc. This process takes place in parallel, breaking the entire visual world down into discrete elements that we initially process independently, and then only later “see” in our mind’s eye as a whole.

Dan Roam, interviewed by Guy Kawasaki

The basic idea is that we can perceive solutions to abstract and complex problems visually.  Visualization becomes a compelling vehicle for communication too.

Visceral Examples

Instead of writing a long string of words to describe the power of communicating visually, we’ll give you a couple examples.

One of Guy’s ventures is a company called Alltop, the goal of which is to find the valuable search results and present them to you.  Alltop is acknowledging a weakness in the search results created by algorithms – whatever the ranking mechanism, it is imperfect.  Alltop’s goal is to eliminate the pain of wading through useless search results to find the “nuggets” of useful results.  Does that explain the idea sufficiently?  What if you looked at this picture, from Guy’s recent blog article, showing a drawing by Dan of the concept described in this paragraph.

There’s a company called Slydial that allows you to make calls directly to someone’s voicemail.  A few minutes of poking around their website will give you an idea of what they do.  If you also read the FAQ and watch the videos, you can infer how it works too.  Or you can just look at the following drawing:

[click for larger version] * Note – depending on your age, the weird boxes are either obviously reel-to-reel recorders, or they are apparently happy robots that are excited to record your message for you.

Instead of calling someone in hopes of leaving them a message (because you don’t want to talk to them), you call Slydial, tell them the number you want to reach, and record a message.  Slydial then calls the voicemail of the person and replays your message directly into their voicemail.  In some cases, the person’s cell phone will even show a “missed call” from your number.

Whiteboards Rock

I’ve been heard to utter the phrase “I can’t think without a whiteboard.”  Whiteboards make for great visualization tools.  In my presentation at ProductCamp Austin, after a quick sojurn through my meager slide deck, we switched to the whiteboard.  With me at the whiteboard, the entire room was able to create an example Ishikawa diagram, first exploring an example problem with a concept map, and then building the associated ishikawa diagram.  The combination of collaborative teaching and visual expression and learning was very effective.

There’s an entire industry, now, built around electronic whiteboards.  Ten years ago, I was at a client using a copyboard – a whiteboard that would rotate the screen (like those old cloth-reel towels in restrooms) and a scanner built into the side of the whiteboard would copy what you had drawn, printing out a black and white copy of your diagram on thermal paper (the kind that used to be in fax machines, and that curls up after printing).  Five years ago, I was able to use an electronic whiteboard that detected the location of (and color of) the markers you were using.  It would detect when you were pressing down to write, triangulate the position of the pen, and create a digital copy on your connected computer.  Now those devices can be used interactively too – you can use a projector, pointed at the whiteboard, share the drawing real-time with remote viewers, and probably any number of other uses.

This matters, because you want a way to capture and share the drawings you create.  If you manage your information and communication well, it’s like slingbox + tivo for whiteboards.  View them any time, anywhere.  If you’re a product manager or business analyst, this gives you an easy way to embed drawings and diagrams within the traditional requirements artifacts.  Electronic copies of the drawings can be incorporated where they are needed most – leveraging context and providing clarity for your readers.  They dramatically help you when writing for an audience that does not have the context you have when creating the document.

Data Visualization

This is yet another incredibly valuable area of study – visual presentation of data.  Networks, connections, values, trends, everything can be visualized.  Check out this article from Smashing Magazine if you want to open pandora’s box into the current cutting edge(s) of data visualization.  If you’re a data-geek or a visualization-geek, my apologies.  This article will suck you into a black hole of great visualization ideas from which you may never recover.

Requirements Visualization

The only reason for documenting requirements is to communicate those requirements.  You can do it with text, or you can do it with analytically-saturated text, combined with gripping and clarifying visuals.  Make sure you have the following visualization techniques in your communication toolbox.

• Structured Requirements (or including interaction design) – this simple approach (and diagram) puts everything into perspective, from business goals to detailed specifications and to test plans and implementation.
• 
• Ishikawa Diagrams – demonstrate the cause-and-effect relationships that articulate why something is important to your stakeholders.
• 
• Class Diagrams – an explicit and expressive way to describe the business domain, providing context for your requirements.
• 
• Process Flows – there are many ways to do describe processes, from simple flow charts and sequence diagrams to BPMN process models (24-article tutorial & free visio template).
• and and
• Use Case Diagrams – no, not the UML use case diagrams, they are next to useless.  These are simple sketches that make a complex use case crystal clear.
• 
• State Transition Charts – show how objects can change their state over time (an order is placed, then paid, then filled or cancelled)
• 

What are your favorites (and why)?

The Cause and Effect diagram is also known as a fish bone diagram, because it resembles the skeleton of a fish. Using a cause and effect diagram can be the most effective way to define the problems that you intend to solve with your product. Get your stakeholders engaged in your program with this compelling visual!

Getting To The Root Of The Problem

In our recent article about writing good problem statements, we pointed out a common mistake people make with problem statements – they confuse the manifestation of a problem with a problem.

Problem manifestation [noun] – an example of a way in which a problem is exhibited, without appreciating the true nature of the problem. Ex: The problem manifestation is that the tires on my car are under-inflated. The problem is that my car is too expensive to maintain.

This distinction is relevant. The cost of operating the car is too high. That is the problem. It happens to be that one reason that the cost is too high is under-inflated tires. If you focus your energy on getting properly inflated tires, it will help (by improving fuel economy a little, and by reducing the frequency of tire replacement) with costs anecdotally. But you will not have solved the problem that costs are too high. Unless you get lucky. Costs can be high because the engine is inefficient or damaged, the aerodynamics of the car are bad, or any of a number of reasons. If you solve the problem by addressing a single manifestation of the problem, without understanding the whole problem, it is only because of luck.

Your Problem Statement is The Problem

In the comments on that article, The Demon points out that it is not always easy to identify the right level of abstraction for your problem. The cause and effect diagram makes it brilliantly simple not only to get to the root of the problem, but to communicate this cause-and-effect hierarchy of problem decomposition.

Cause And Effect Diagram Example

The cause and effect diagram is so visceral that the easiest way to communicate how it works is to show an example. Here’s what the cause and effect diagram would look like for the example problem above, where the cost of operating the car is too high.

[larger image]

The main problem is that the cost of operation is too high. This is the far-right, or fish-head part of the diagram (it is sometimes called a fish bone diagram).

The problem can be decomposed into three separate problems: spending too much on fuel, maintenance, and payments. Each of those problems can be further decomposed. Note that “under-inflated tires” appears twice – once as a cause of low miles per gallon (MPG) and once as an excess maintenance cost.

Alternately, you could recognize that spending too much on fuel could be due to lower fuel economy or excessively high prices. You could then choose to decompose the problem slightly differently:

[larger image]

Either approach results in crystal clarity that under-inflated tires is one root cause of low fuel economy, which is one cause of excessive spending on fuel, which is one cause of excessive operating costs. This visual approach helps significantly when trying to identify the right level of abstraction for expressing the problems in your problem statement.

Problem Abstraction Is A Side Benefit

The really cool part is that the help you get in finding the right level of abstraction for your problem is just icing on the cake. [Ed: No jokes about fish-bone cake. Ick!]

The real benefit comes in communicating and validating the problem decomposition with your stakeholders.

Someone questioned me once on the value of writing passionate requirements. Show one of these to your team, and you’ll get enthusiastic, passionate responses. You’ll get kudos from the business for demonstrating that you understand their needs. You’ll get praise from the implementation team for providing them with context.

Using Visio To Create A Cause And Effect Diagram

Creating a cause and effect diagram in Microsoft Visio is really easy, there’s a built in template, and it’s a good one. Create a new drawing and select the “Cause and Effect Diagram Shapes” template (under “Business Process”):

Visio will create a new drawing with a blank cause and effect diagram set up for you:

Fill in the boxes with the large problems. To get to the next level of detail (such as “Fuel Economy is Too low” in the last example), select the “Primary Cause” shape and drag it onto the diagram. Attach the arrowhead to one of the branches (the fish “ribs”) and start typing. For once, Visio’s default layout is where you want it.

To get a secondary cause shape (such as “Bad Aerodynamics” in the last example), select the “Secondary Cause” shape and drag it onto the diagram. Attach the arrowhead to the “primary cause” arrow you just created.

Conclusion

You already have a good justification for defining problems at the right level of abstraction. Now you know how to easily create a cause and effect diagram to find the right problem definition. As a bonus, communicating with stakeholders just got a lot easier – include this in your BRD.

A rose by any other name…

When we’re learning how to write in high school and college, we’re taught that synonyms make our writing more exciting. In fact, not using synonyms can make our prose clumsy and awkward.

When it comes to requirements, the last thing you want to do is use synonyms. Except sometimes.

Writing Stylish Requirements

One of the lesser appreciated rules of writing good requirements is to write requirements with good style.

Your writing style needs to take into account the fact that not all of the readers of your requirements will have English (or whatever language you write in) as their primary language. The readers may have as a primary language one that does not have the same idioms, constructs, and “common” terms as the language of the requirements. Those readers are already at a disadvantage, having to reverse-engineer colloquialisms, decode complex sentence structures, and look up the definitions of terms that they don’t know.

Even readers who share a common language [Great joke from Eddie Izzard: "Britain and America are two countries separated by a common language"] probably will not share the same idioms and colloquialisms.

Writing clearly and unambiguously requires that you use more formal language when writing requirements. Synonyms may make for better style when writing prose, however, they can confound your readers and increase the risk of misunderstanding when used in requirements documents

Avoid Synonyms

Synonyms introduce ambiguity into your requirements. Consider the following examples:

• The user will have added items to her shopping cart while browsing the website. When she is ready to purchase the items in her cart, she will click on the “cart” icon. All of the items in the basket must be priced with the most recent pricing rules.

Are you pricing the items in the basket, the cart, or the shopping cart? That may seem obvious to you, since most of us are familiar with the shopping cart metaphor in e-commerce transactions. What about the following?

• A round bit must not rotate within the head when the vice is adequately tightened.
• The vice will be tightened with a key measuring no more less than two inches in diameter.
• A moment of 10 inch-lbs applied to the chuck will be considered adequate for tightening.

If you don’t know that chuck and key are synonyms, you’re in trouble. If you don’t realize that the vice and the head can also be considered synonyms in this context, you are in more trouble. You should use the same terms throughout your requirements document, when referring to the same object or concept.

Except when you should use different terms for the same objects.

Embrace Synonyms

There are times, however, when synonyms can bring clarity to an otherwise confusing document. This effect is less powerful than introducing confusion, so when in doubt, don’t use synonyms.

Synonyms provide clarity when used in a particular context. If you sell cars, then you have a customer. Imagine you also provide financing (products) for your customers. In the context of negotiating a price for the car, the customer is a customer. In the context of negotiating an interest rate, the customer is also a borrower.

Validating the requirements for the lending process may be much easier when using the word “borrower” instead of “customer.” What you are striving for is clarity of language, and when interacting with stakeholders who have always used the term borrower, you can use that term in your documentation.

The key is to identify the synonym in the glossary of terms. You have to identify the synonym as being associated with both the equivalent term, and the context in which the synonym applies.

The customer at the car dealership can be the purchaser, the borrower, and the driver. It all depends on context. When you manage the synonyms within your glossary you can use the different terms. But you should only use them when they reduce ambiguity – not when they introduce it. Even with our example, the customer and the borrower might be different people – so make sure that the synonymous terms represent the same object, and not potentially different ones.

Separation of business rules from requirements is a good thing. Not because of semantic distinctions, but because it allows you to write better software, write it faster, and change it more easily. This article is a response to an excellent comment on our recent article about hidden business rules. Thanks for challenging the idea – it either eliminates it from discourse or makes it stronger, and we all benefit. Here’s an attempt to make it stronger.

Goals of Separating Rules from Requirements

Writing software ultimately involves coding up an implementation that both satisfies the goals of the customers and enforces the rules by which that customer chooses to achieve the goals. This is the traditional way to write software – define the goals, and all of the enhancing, constraining, and clarifying details, then implement it. There are some inefficiencies to this approach, but they are in the “getting great at writing software” bucket, not the “avoiding failure at writing software” bucket. Consider this the medium priority goal of separating rules from requirements. In a Kano analysis, this is a more-is-better benefit.

When we set out to write software, it is with intent. That intent encompasses processes, rules, and requirements. The combination of all of these could be described as a summation of intent.

Maintaining software is expensive. When you design an implementation, you (should) think about what is likely to change when making your design decisions. The greater the probability or frequency of change, the easier it should be to make those changes.

Intent changes. Agile processes start with a premise that even if the true intent were fixed, our understanding of intent would change, as soon as we get what we asked for. In practice, both our understanding of intent, and the actual intent change over time. To make the language less cumbersome, for the rest of this article, when I refer to intent it is our understanding of intent – and changes to intent represent both changes in the true intent, and changes in our understanding of it.

When developers think about software maintenance, they often think about it in terms of bugs and features. What needs to be fixed, and what needs to be added (or removed)? To make a significant impact on the cost of maintenance, we have to take that perspective to the next level. Set aside fixing bugs (where bugs are “does not work per the requirements”), and think about the new features. The new features truly represent new intent. Or in an agile process, it may be the recently revalidated, previously identified, next most valuable intent.

In both cases, intent is a moving target, and changes in intent drive changes to the existing software. To minimize the cost of making those changes, our implementation should be structured such that the most common changes are trivial to implement – ideally, they won’t even require changes to the code. When you can change the behavior of an application without recompiling the application, you significantly reduce the effort required to define,develop,test and deploy an update to the application. And you can also dramatically reduce the time required to make the change.

This is the high priority goal of separating rules from requirements: increase the speed, and decrease the cost of changing software to match changes in intent. I’ll say it again in bold.

The primary goal of separating rules from requirements is to increase the speed and decrease the cost of updating software to match changes in intent.

While the cost reduction part of it is nice, it is the speed element that can be the most compelling. James Taylor and Neil Raden wrote about this in their book, Smart Enough Systems. We accept the premise that abstracting the implementation of volatile rules from the rest of the software provides benefits in speed of delivery on an ongoing basis. And that is the primary driver for the separation of rules from requirements. If you don’t accept that premise, then the only benefit comes from improved documentation style, structure, and standardization – all somewhat subjective benefits.

Visualizing The Benefits

Here’s a timeline showing the benefit of agility – being able to deploy and update faster.

The maroon curve represents “traditional” deployment – where the implementation of volatile rules is no different than the implementation required to support requirements. It will take longer to deploy initially (but not necessarily much longer), and it will take longer to make changes (when the rules have been changed). The upward sloping line starts displaying accumulated value as soon as the software is released. When the next iteration is released, the rate of value accumulation will go up. There is one iteration displayed in the timeline.

The green curve represents deployment with volatile rules abstracted in the implementation. This could be as low-tech as implementing field-level validations in a properties file (that is interpreted by the application), or as high-tech as integration with a rules-processing engine or service. This implementation begins accumulating value a little bit earlier, but at the same rate (keeping prioritization and other factors equivalent). The first iteration happens more quickly, so the slope of the curve increases earlier. The length of iteration has been shortened enough that a second iteration can also happen. This further increases the relative rate of accumulation of value. The longer this pattern goes on, the greater the disparity.

Encouraging This Behavior

Abstracting the rules from the requirements will make it easier for developers to absorb and design for those rules. Further, once the rules have been separated from the requirements, it is easier to identify which rules are the volatile rules. And that enables developers to make smart decisions about when to abstract the implementation, and when to embed it.

You could abstract only the volatile rules from the requirements, and leave other rules embedded within the requirements. There are three good reasons for separating all of the rules from the requirements.

The first reason is one of consistency of documentation, and arguably style. Your communication will be more effective when consumers of the documents know that all rules are treated in the same way. If developers have to look in the requirements for some rules, and a table of rules for others, they are more likely to miss something. Subject matter experts who are validating the rules will also be able to do that job more effectively when they are documented similarly.

The second reason is that by separating all of the rules, you will better be able to identify the ones that are volatile. You can more easily evaluate the rules as a whole, and formally or informally characterize their frequency and likelihood of change. The rules for management of available products and the calculation of risk in a portfolio are likely to change frequently. The rules that represent FAA regulations are likely to change infrequently. You can better assess this data when dealing with a cohesive set of rules.

The third reason is that separation of the rules will imply to developers that they should at least consider separation of the implementation. Especially if, in your documentation approach, you identify which rules are volatile.

Conclusion

There are differences in rules and requirements. While the content of how they are used when developing software may be only semantic, there are practical benefits to separating them. Separation of rules and requirements in a documentation approach will make it easier for your development team to implement solutions that separate volatile rules from the rest of the code.

And this separation will make the software more valuable, more quickly.

Effective communication of requirements requires more than documentation and broadcasting. Effective communication requires interaction and collaboration. Alistair Cockburn addresses this in his analysis of project successes and modes of communication.

Alistair’s Article

Alistair analysed three dozen projects over the course of two decades. He was trying to find common approaches and processes that would correlate with or predicate software project success. What he found instead was that people and communication had more of an influence over the success of a project than process. This may be the source of the “people trump process” quote.

Hat tip to Jeremy Miller, The Shade Tree Developer, for the reference, as part of his excellent article describing the ideal software team.
In his article, he presents a diagram of different forms of communication and their effectiveness. We’ve redrawn Alistair’s diagram here.

The most effective communication is person-to-person, face-to-face, as with two people at the whiteboard. As we remove the characteristics of two people at the whiteboard, we see a drop in communication effectiveness. The characteristics that get lost are:

• Physical proximity. I am at a loss to explain why, but being physically close to the other person affects the communication. Whether it is three-dimensionality, timing, smell, or small visual cues, physical proximity matters.
• Multiple modalities. People communicate through gestures as well as words, often making a point by gesturing, raising an eyebrow or pointing while speaking.
• Vocal inflection and timing. By speeding up, slowing down, pausing, or changing tones, the speaker emphasizes the importance of a sentence, or perhaps its surprise value.
• Real-time question-and-answer. Questions reveal the ambiguity in the speaker’s explanation, or the way in which the explanation misses the listener’s background. The timing of the questions sets up a pattern of communication between the parties.

Characterizing people as non-linear, first-order components in software development, Alistair Cockburn

Visualizing The Analysis

When you look at the characteristics Alistair identifies, and overlay them on the diagram, you see the following:

The forms of communication can be clustered into two groups, one clearly more effective than the other. Within each group, there are more distinctions.

• Physical Presence vs. Artifacts. Collaborating in front of a whiteboard or on the phone is more effective than an email exchange. While eMail and instant messaging allow for near real-time interaction, they lack the cues that come from physical interaction. Our brains are wired for listening and looking as the means to communicate. You can absorb information and express ideas through artifacts, but it is less efficient. Artifacts that you create lack the instinctive elements of nuance in communication. Active listening skills are refinements of what we’re already wired to do – and they make physical communication more effecient than when you write something down.
• Interaction vs. Broadcasting. Strikingly distinctive is the difference between interaction and broadcasting. It is the difference between a community and an audience. Intuitively, you know that “throw it over the wall” is bad. Alistair’s research validates this. Determining the correctness of requirements requires interaction. You can use use cases to verify requirement correctness – but doing it without interaction is less effective.

Conclusion

Product requirements management requires communication. Different teams use different processes, and all processes involve communication. Effective communication must be interactive, not broadcast. Physical communication is more effective than communication with artifacts.

Artifacts serve a purpose – providing context, continuity, and a record of what has gone before. They are important for those goals, but relying on them as a communication vehicle in the absence of interaction will reduce the effectiveness of your team.

You knew it would happen eventually, the big ten rules of writing requirements has become the big twelve rules. Maybe scope creep isn’t such a bad thing after all. Writing style plays an important role in writing requirements too.

Background

The original series started with a summary of the ten rules to writing good requirements, and then we followed up with ten articles with details of each rule. Then we added another one – writing correct requirements. Today’s article brings us to twelve by adding an element of style.
The Big Ten Eleven Twelve Rules of Writing Requirements

1. Valuable
2. Concise
3. Design Free
4. Attainable
5. Complete
6. Consistent
7. Unambiguous
8. Verifiable
9. Atomic
10. Passionate
11. Correct
12. Stylish

Stylish Requirements

For Buzz Lightyear, in the movie A Toy Story, the difference between falling and flying was simply a matter of style.

Style can also be the difference between a well-crafted requirement and one that is hard to read. And style, applied consistently across requirements makes it easier to view them as a whole, and identify gaps and inconsistencies. This ease of comprehension matters when trying to achieve correct, consistent, complete requirements.

Elements of Style

Usually, when we talk about writing style, we are talking about grammar rules. Documenting requirements requires a specialized, almost esoteric form of writing. And this form of writing benefits from applying some consistent elements of style. We should use the same style when writing all of the requirements for a given product or project – and ideally for all projects within a company.

Styles are like elbows – everybody’s got them – so it isn’t reasonable to expect everyone to use the same style. Develop a style, and use it.

Here are some of the ingredients that go into our style recipe:

• Thou Shalt
• Prioritize Explicitly
• Pick The Best Perspective
• Non-Negative Waves
• Reference, Don’t Repeat
• Gender Indifference
• Syntactic Parallelism

Thou Shalt

The analyst shall use the word shall to express a requirement. Other acceptable words are must and will. When writing requirements, use phrases like “The system shall process…” or “The user shall be able to…”

Prioritize Explicitly

In More About Software Requirements by Karl Weigers, he pointed out his dissatisfaction with the way some teams capture prioritization implicitly in their requirements through the use of shall / should / may language. “Shall” requirements are high priority, “should” requirements are medium priority, and “may” requirements are low priority.

Ugh. What a horrible idea. I had not seen anyone doing this. Karl’s right, this is an awful idea. Especially when teams involve people who don’t share the same native language or culture. Priority should be called out explicitly.

By the way, Karl’s book is great. If you gather, write, or manage requirements, you should own it.

Pick The Best Perspective

Some requirements are written “The system shall…” and others are written “The user shall…” These two approaches represent two different perspectives. In an ideal world, one perspective or the other would be most appropriate for all of the requirements within a document. We would also have free energy, world peace, and total enlightenment.

We could force ourselves to consistently apply the same perspective for all of our requirements. Jumping through linguistic hoops to write this way would violate our rule of writing clear and concise requirements. For each requirement, we choose either “system” or “user” as most appropriate.

• The system shall process invoices nightly.
• The user shall input their shipping address.

Imagine trying to write either requirement the other way (replacing system or user with user or system respectively).

Non-Negative Waves

Another great suggestion from Karl. Don’t write requirements in the negative, write them in the positive. A couple examples:

• “The system shall not permit orders with more than 1000 items.” Write this as “The system shall only permit orders with 1000 or fewer items.”
• “The user shall not be able to access data to which he does not have sufficient authorization.” Write this as “The user shall only be able to access authorized data.” [Note - additional information about authorization would be required to make this complete. See the next tip.]

Reference, Don’t Repeat

The same concept, construct, or requirement may be repeated in multiple places within the requirements for a product. It should not be duplicated, it should be referenced. In the previous example, we used the requirement “The user shall only be able to access authorized data.” The will be other requirements around how authorization is defined and managed.

We could duplicate an explanation of what authorization implies in each place where we reference it. What would be more manageable would be to reference a single explantion of authorization.

Gender Indifference

A hot topic for grammarians is the proper use of gender in documents. Should we use “he” or “she” or “s/he” or “they?” What about “one” or “the user?” This is a matter of preference. We prefer indifference.

We arbitrarily define the gender of any particular user as male or female within a requirement or example. We try and maintain a balance by having roughly half of our entities be female, and half male. In my personal opinion, this makes for stronger writing than using the contrived s/he or a plural form like they.

When defining actors and use cases, the actor’s gender is generally not specified. The actor is described as a role. The text of the use case, especially when using an informal use case, is where this style is applied. We maintain gender-consistency for any particular actor in a single use case, we don’t try and assign genders to actors and maintain consistency across all of the use cases.

When defining personas and writing user stories, we will match the gender usage in the story to the gender of our persona.

Syntactic Parallelism

This is an obnoxiously complex way of saying “write with consistent structure” – but it at least got you to scroll down and read this far.

“He came, he saw, he conquered” is much more powerful than “He came, he saw, his foes were conquered.” Likewise, “The system shall process the request, retrieve the results, and present them to the user” is better than “The system shall process the request and retrieve the results and the user shall view them.” [Note: The example above violates the atomicity rule, but is illustrative.]

Conclusion

Style is not something that can be quantified any better than art can be quantified. The best we can do is follow guidelines and apply our skills. And as good writers will attest, these are guidelines. It is better to violate them when appropriate than to rigidly adhere to them in spite of the awkwardness of the results.

Having a consistent style will help with readability of the requirements. Define your style and stick to it.

We talk about characteristics of good requirements, including completeness, correctness, and clarity. But how do we assure that our requirements are complete, correct, and unambiguous? Simple, Captain, with logic. And how do we improve our logical skills?

Short Pitch For Logic

Logical thinking helps us in many areas of life, but for this article, we’ll talk briefly about how logic helps us avoid incomplete, incorrect, and ambiguous requirements.

• Incomplete Requirements – logic allows us to look at the whole, and develop an intuition about the completeness. There are many models that can be used for capturing requirements, like the state-transition diagram that Seilevel uses (state table). The state table works because it is rooted in logic. Essentially, it is a visual representation that makes a specific type of oversight scream at our frontal lobe to be discovered. Logic dictates that all transitions must be addressed (or explicitly prevented).
• Incorrect Requirements – logical inconsistency helps us identify when our requirements contradict themselves. This is more effective when documenting highly interdependent processes. Logic also allows us to apply domain knowledge, or extra-domain knowledge to the requirements we elicit. If something is inconsistent with what appears to be (otherwise) similar from a different domain, logic helps us identify the incongruity, and ask clarifying questions.
• Ambiguous Requirements – Mavens help us identify when terms are ambiguous in the context of a domain. Amateurs can apply logic to identify ambiguity in language. This parsing of speech is applicable in any domain. And even more important when working on a team that doesn’t share the same primary language and idioms.

Improving Our Logical Thinking

One of the business analysts on my team shared a fantastic site with me last week. The LSAT Logic in Everyday Life podcast is a weekly(ish) podcast from the Princeton Review. The author approaches current events and other everyday situations from the perspective of a logician.

The podcasts are intended to help people improve “the kinds of logical thinking tested on the LSAT.”

Well, it is the same kind of logical thinking that helps us write better requirements. Each recording is about five minutes long – I’ve burned them onto a couple CDs that are in my car for the drive home from the airport. The general theme, at least in the earlier episodes, is in exploring the logical fallacies of many different arguments, positions and conclusions. Discussions about how to apply logic to strengthen and weaken arguments are also included.

As writers of requirements, we can benefit from this as well. You should all listen to at least one of them, it only takes about five minutes. I believe you’ll be very excited.

Pair programming is a bit of a foreign concept for many people in business. A few years ago, it was foreign to most programmers too. Pair programming is a powerful technique for software development because it allows two people to look at the same problem/solution from two different perspectives at the same time. Would that same approach work for business analysis?

Pair Programming

We haven’t written an introductory article on pair programming, and after reading what James Shore has written on pair-programming as part of his book, The Art of Agile Development, there’s really no room for improvement.

Pairing involves two programmers (or, less often, a programmer and a customer, tester, or other team member) working together to accomplish a single task. The person with the keyboard—the driver—focuses on the details of the task. He thinks tactically. The other person—the navigator—keeps the big picture in mind, ensuring that the task fits into the project as a whole, looking for ways to improve design, and keeping track of team guidelines. She thinks strategically.

James Shore

The interesting dynamic that makes this work is that the two programmers switch roles on a regular basis. As frequently as every half hour. Read this intro to get a better feel for it.
[Segue: Please read, review, and provide feedback for James on his book. It is awesome that he is doing the book this way, and you also get to read the early stages of a great book before most people.]

Strategic and Tactical Programming

Great programming is about both design and execution. The navigation and the driving, as James puts it. Having been a pair-programmer in a past life, I can attest to the power of this dynamic. When I think about really powerful solutions and innovations, they have come from (or at the least been improved by) collaboration.

Even without pair-programming, we can get the same benefits through feedback and reviews of our designs and our code.

How does this apply to business analysis?

Strategic and Tactical Documentation

When we create requirements documents, use cases, object oriented diagrams, and other artifacts, it is no different than programming. Instead of source code being written for a compiler to read, our documents are written for a person to read. We just don’t have the benefit of a compiler to point out our grammar mistakes, a code-styler to suggest more concise ways to write or more universal terms to use, or a set of automated tests to identify ambiguity and incorrectness. We have to get feedback the old-fashioned way, by reviewing our documents. The ease with which stakeholders read our documents is analogous to the performance benchmarks for code.

The organization of our documents is analogous to the design of a programmers code. The details we write are the embodiment of that design, just as code is the manifestation of the design. There are significant parallels.

We should be able to benefit from pairing when writing requirements documents.

The Biggest Improvements

When I think about the biggest improvements that I’ve seen in the documents we are creating on our team for my current project, almost all of them have come from collaboration. Formal and informal reviews of documents, brainstorming about how to represent a process, and discussions about the tradeoffs of documenting things in one way versus another.

This feels a lot like the code-reads we do as programmers. People who have pair programmed consistently admit that it is better than the do-review-redo cycle of traditional development processes. Would the same hold true for documenting requirements and processes? What about any writing at all?

Here’s another quote from James:

Pair programming produces code through conversation. As you drive or navigate, think out loud. Explain your assumptions, your short term goals, and any relevant history of the feature or project. If you’re confused about something, ask questions—the discussion may enlighten your partner as much as they do you.

Sounds a lot like the best parts of the documentation process to me.

What Do You Think?

Do you think it would work? Do you think you could sell it (justify the staffing of it)? Is there a downside?

We ran a series called Writing Good Requirements – The Big Ten Rules in May 2006. Bloggers are notorious for not being able to count. We had ten rules at the time, and now we’re adding an eleventh. Writing Correct Requirements may have been the unwritten rule, but now we take a look at it.

Background

The original series started with a summary of the ten rules to writing good requirements, and then we followed up with ten articles with details of each rule. And now we add another one – writing correct requirements.

The Big Ten Eleven Rules of Writing Requirements

1. Valuable
2. Concise
3. Design Free
4. Attainable
5. Complete
6. Consistent
7. Unambiguous
8. Verifiable
9. Atomic
10. Passionate
11. Correct

Correct Requirements

Correctness in requirements is simply about getting it right. We wrote previously about how to apply use cases to creating correct requirements. Writing requirements correctly is as much about getting accurate information as it is about accurately documenting the information we gather.

Correctness applies in a context. “Are these the right requirements to achieve goal X?” Verification is the process of verifying that we identified the right requirements to achieve a particular goal. Validation, on the other hand is the process of assessing requirement completeness. People often swap these terms as being nearly synonymous.

Verification Techniques

To verify that requirements are correct, we start by asking two simple questions. Here’s an example for writing a software requirements specification. Set aside for the moment that some people consider this to be design, although from a developer’s perspective, it is a specification (or requirement). This serves as a good example for business analysts.

• Does each of these requirements contribute to achieving our goal? If a requirement does not help us achieve the goal that it supports (in a structured requirements framework), it is not a correct requirement. Either the requirement is placed under the wrong goal, or it truly doesn’t belong.
• Can our goal be achieved without these requirements? If our goal can be achieved without the requirement, then it isn’t required. “The system shall generate a report of all outstanding customer bills” is a requirement. If the goal is “Identify a customer’s unpaid bills”, then “The system shall display any unpaid bills for a customer” is a more correct requirement, because the goal can be achieved without a report.

A market requirement (useful to product managers) would be “Reduce the cost of accounts payable by 5%.” There is an ideation step in going from documenting market requirements to documenting product requirements. In that step, a product manager will decide how to approach, with her product, the reduction of accounts payable. Consider the following approaches and requirements and their hypothetical correctness verification.

• Approach: Remind customers of outstanding bills. Requirement: “The system shall generate past-due notices for all bills on the monthly anniversary of each bill.” This requirement would not be correct if bills are issued with 90-day terms, because the bills are only due, not past-due. We identify that this requirement is incorrect because of the semantics of past-due billing, and the hidden complexity of varying billing terms.
• Approach: Relax outstanding debt by 5%. Requirement:” The system shall reduce the outstanding balance of all past-due accounts by 5%.” This requirement would reduce accounts payable amounts, but it would not address the opportunity cost of the missing funds. Companies earn interest on credit balances, and pay them on debts. By decreasing the amount owed, a company would not have any impact on the amount that it could have earned (or avoided paying) in interest. This does reduce the size of the accounts payable amount, it does not achieve the goal.
• Approach: Increase prices for high-risk customers. Requirement: “The system shall adjust product prices per [referenced actuarial table], to reflect the risk of late payment.” This would not reduce the cost of accounts payable, although it might increase the profitability of the product (and might not). Since this doesn’t directly contribute to achieving the goal, the requirement is incorrect.

Context

As the examples highlight, we have to understand how the market requirement works. A knowledge of the billing rules for our customers, as well as an understanding of the cost of capital are both required.

Conclusion

Writing good requirements demands that the requirements be correct. Correctness can only be identified with context and domain understanding. Correctness can be determined by asking if a requirement achieves the goal, and is required to achieve the goal.

Monty Python and the Holy Grail is one of the funnier movies ever made. It was rereleased a couple years ago with digital remastering, deleted scenese, and lots of extras in a two-disk version. The rest of this post will make you chuckle if you’ve seen the movie.

Bugs Can Come From Anywhere

Software bugs can come from any of several places in the SDLC (software development lifecycle).

SMEs That Aren’t Experts Give Bad Data

“But how do you know she’s a witch?”

When we interview subject matter experts and business owners, they may give us misleading or incorrect information. They may lack a key insight or understanding, or they may oversimplify or overcomplicate the problem.

Stakeholders Change Their Minds

“Blue. No, Yellow! Aaaarrrrgh”

Kent Beck argues that customers will not know what they want. A SME needs to be able to clearly identify what they need.

Poor Listening Skills Cause Miscommunication

“Right. We’re not to leave, unless Prince Herbert comes with us.”

Even when our customer knows and expresses his requirements, we may not listen correctly. Active listening is a key technique to avoiding this miscommunication.

Ambiguous Documentation Prevents Communication

“If he were dying, he wouldn’t have bothered to write ‘Aaaaaarrrrgh’.”

We have to document our requirements unambiguously if we hope for people to interpret them properly. We also have to keep in mind that we are writing for someone else to read the docs eventually – not just taking dictation. Writing for the implementation team can be even harder when outsourcing – we limit our ability to clarify and reach a common understanding.

Back to our regularly scheduled programming…

“Why?” The question is our inspiration and our muse. “Why?” is the justification for our requirements. The key to identifying “What?” and “When?”, which lead to “How?” and “How Much?” But there is another use for “Why?” – communication of intent (with stakeholders and implementers). Requirements documents are artifacts, but they are also dynamic documents. By documenting “Why?” a requirement is a requirement, we make it easier for future readers to understand.

Meeting Debriefing

I was observing a meeting earlier this week where a member of my team was reviewing a “finalized” requirements document. The requirements in that document were gathered previously, and validated for both correctness and completeness. This review, another step in the elicitation process, involved stakeholders who were not involved in previous sessions. The meeting was not an efficient one.

Inefficiency

Over the course of two hours, the team reviewed and discussed no more than ten requirements. The project is a migration project from a legacy system to a new solution. There are minimal process changes in this phase of the project (and therefore the review is looking minimally at process re-engineering).

The following are some of the questions asked by participants in the review:

• What is the difference between those two [variations of] start dates?
• Why do we need that information in the system?
• Why can’t we simplify X to Y?

The answers to these questions (each was asked multiple times about most of the requirements that were reviewed) generally involved relatively detailed explanations, hypothetical examples, and occasional diagramming of business object relationships to effectively communicate why the existing requirements had been written, and why they had been written in the way they had been written.

Perception

At the end of the meeting, one of the project sponsors expressed concern that a “final review” meeting was so ad-hoc and disorganized. Our sponsor now has a fear that requirements are being missed, or documented incorrectly.

Anecdotally, there were no significant changes to those requirements as of the end of the meeting. Why did we have to spend 20 man-hours to make no perceptable changes?

Because we didn’t document the answers to these questions the first time!

Document Creation

The creation of, and initial validation of the requirements document involved interviews, contextual inquiries, and side-by-side comparisons and gap-analysis with existing process documentation. The resulting requirements were documented.

All of the questions that were raised in this meeting had been raised in previous sessions. None of the answers had been included in the documentation. And the overall project is large enough, and complex enough that people inconsistently remembered or completely forgot the justifications for the requirements.

Documenting Why

Including the justifications, scenarios or examples, snippets of business object models, and other supporting information would have prevented much of the debate. If we had included the underlying “Why” data that drove the “What” data (the requirements) in our documentation, we would have avoided rehashing these same issues.

It isn’t enough to ask why during elicitation – we have to document the justifications along with the requirements.

Kathy Sierra writes (another) great article at Creating Passionate Users. This time, she talks about why users don’t upgrade and presents ways to get users to install the latest version. We focus in this article on one way in particular – using goal-driven documentation to encourage upgrading.

Background On Documentation

Over the last couple of days, we’ve written about how to structure documentation to define what users can do with the software, instead of capturing what the software can do for users. This reverse approach uses user goals to guide our documentation. We also presented, more concretely, how to trace and manage our goal-driven documentation with use cases.

We can leverage this documentation approach to achieve two additional benefits:

• Encourage users to install new upgrades
• Encourage users to migrate from other applications to ours

The same factor is at play in both situations – users already know how to use their existing software, either a previous version of our software or a competitors software. The fundamental question for users is “How will I do what I need to do?” This is a major barrier to both upgrades and migration from other applications.

Kathy On Upgrades

Kathy’s article on why users don’t upgrade is awesome. She creates a great visual graph (shared via her CC license) of the user’s perspective on upgrades:

Why they don’t upgrade (and what to do about it)

Kathy goes on to list several approaches to address the problem, all of them fall into either “make them want it” or “make it easier.” We will focus specifically on how writing goal-driven documentation can help.

Make Them Want It

We must apply the same prioritization approach to defining upgrades as we do to defining the initial release. This assures that the most valuable not-yet-implemented goals are addressed in the new version of the software. If we are using Kano as a framework for prioritization, we have the added benefit of effectively lowering the suck-threshold.

Make It Easier

We can make design decisions that make software easier to use. We can also follow Kathy’s other good suggestions. And we can write our documentation to make it easier for users to make the change.

Goal-driven documentation has two effects on the curve Kathy drew above. Here’s the same curve, representing a typical software upgrade:

With goal-driven documentation, the curve is shifted up and to the left:

This shift can be analyzed as two different factors:

The goal-driven documentation allows users to climb become more competent more quickly – effectively lowering the suck-threshold. When applied to upgrades, it reduces the size of the drop – preventing users from re-entering the suck-zone.

Faster Climb

Competence is not a measure of how quickly users can do everything the software can do – it is a measure of how quickly users can do everything they need to do with the software. When we define our software to prioritize solving the most valuable problems for our customers, we are defining the set of activities that the users need to do. And we identify this as a set of use cases.

We then document how users will follow those use cases, with the implementation we’ve given them.

This goal-driven approach to documentation helps users climb the competence curve much faster, immediately reaching the “Finally I can actually DO something” point (above the suck threshold). As long as we document the right somethings, we’re all set.

Shorter Drop

We apply this same approach to our upgrades. Those use cases that we’ve added in a new release yield new documentation. Those implementation areas we’ve modified as part of the upgrade yield updates to previously released docs.

Users will have an easy answer for “how do I do it now?” as well as “What can I do now?”

Collateral Benefit

We also get the benefit of making it much easier for users to migrate from other software packages (not just our earlier releases). There are books out there where authors address exactly this problem – Microsoft Word for Wordperfect Users and Java For Cobol Programmers come to mind. By showing users how to do what they need to do, we make it easy for them to switch.

Conclusion

• Goal driven documentation makes it easier for users to learn how to use our software.
• Goal driven documentation makes it easier for users to switch from other software programs to ours.
• Goal driven documentation makes it easier for users to upgrade to new versions of our software.

Yesterday we wrote about focusing our documentation on what our users are trying to accomplish. With a structured requirements approach, or with an interaction-design driven approach, we’ve already solved half the problem – determining what to document.

Our proposed documentation approach is to write about what users are doing with the software, not what the software can do for the users. Using a power drill as an example, we proposed the following representative approach:

1. How to drill a hole in a flat surface (wood or plastic, metal, masonry).
2. How to select the right screw for fastening items.
3. How to drive screws (phillips, flat-head) with your drill.
4. How to stir paint with your drill.
5. etc…

Suddenly, the documentation is helping us to achieve our goals.

Extending Structured Requirements

When we use a structured requirements approach, we have established a framework for defining the problems that our software will solve. We articulate how people solve those problems with use cases. These use cases define exactly what we need to document.

When we view structured requirements, they look like the following diagram:

From Non-Functional Requirements Equal Rights Amendment

We extend this structure by leveraging the fact that the use cases identify the highest priority tasks that users will perform to achieve goals. These are therefore the highest priority tasks to document. The documentation represents how a user would achieve a use case, with the implementation that we’ve created.

We can even trace each portion of our documentation work to the use case that it supports.

Extending Interaction Design

With interaction design, we are again focusing on what people intend to achieve while using our software. Even if we are writing game software (which is designed to be played without a “goal” in the traditional sense), the user still has a goal of “being entertained.”

With interaction design, we would write documentation that demonstrates the way that scenarios play out with the given implementation that we created.

Even when combining interaction design and structured requirements into a hybrid approach, we still have a source from which to define our documentation needs – the scenario.

Summary

We’ve previously defined the benefits of documenting what users do with our software instead of documenting what our software can do for users. In this article we present a framework for defining and tracing that documentation – building upon use cases or scenarios. This documentation approach makes for software that is easier to use, and therefore better.

Why do we write documentation? Because someone told us to write it? Because our competitors have it? Or because we want our software to be easier to use? It should be the third one, but often, writing documentation is an afterthought, and it is deprioritized, and we just get it done, instead of thinking about the goals for doing it in the first place and doing it right.

Instructions for a Drill

Imagine that the instructions for your brand new electric drill had the following sections:

1. How to adjust the speed of your drill.
2. How to change the direction of the drill.
3. How to change the drill bit.
4. etc…

You wouldn’t know very much about how to accomplish something with the drill – you would only know how to operate the drill. What if the instructions had the following sections:

1. How to drill a hole in a flat surface (wood or plastic, metal, masonry).
2. How to select the right screw for fastening items.
3. How to drive screws (phillips, flat-head) with your drill.
4. How to stir paint with your drill.
5. etc…

Suddenly, the documentation is helping us to achieve our goals.

Do The Job (Versus Use The Tool)

We write documentation so that people can more easily do the job, not so that they can use the tool. In our example above, the “use the tool” instructions in the first list would be fine for someone who already knows how to use a drill – it would only teach them the unique elements of how to use this drill.

Software doesn’t present the same set of physical affordances that hardware does. Rarely are there a handful of obvious physical controls begging for interaction – “That looks like a trigger, and the drill looks like a gun – I bet that’s how I make it spin!”. Instead, we have a myriad of choices – buttons, menus, hidden context menus, command line prompts, gestures, etc.

With rare exceptions, we aren’t writing documentation to teach someone how to use our software (instead of some other software they already know, which does exactly the same things). We are trying to teach them how to achieve their goals and solve their problems, using our software.

We defined requirements to solve problems and achieve goals and generate value. Shouldn’t our documentation be written with these same goals in mind?

Creating Competent Users

We’ve written before about Kathy Sierra’s now famous suck threshold. The suck threshold is the minimum level of competence required for a user to feel like they don’t suck when using the software. We talked about it in the context of defining the right number of features to include in the software. More features means more complexity which means users take longer to master the software.

We’ve also talked about how to prioritize features for software to maximize the likelihood that our users will operate above the suck threshold. We have to prioritize for competent users (people above the suck threshold) because beginners aren’t beginners for long, and few people invest the time and effort to become experts.

A key articulation users propose for why software sucks is that they can’t understand how to achieve their goals.

Our Documentation Should Help Users Achieve Their Goals

Pretty simple, really. Many software “manuals” have documentation that is organized to mirror the user interface – a section for each menu, with a sub-section explaining how to use each item in the menu (“How to adjust the speed of the drill”). It is left as an exercise for the user to know when, why, and how much to adjust the speed of the drill. These gaping voids provide a great market for authors – how many trees have died to publish “How to use Access” and “Secrets of Word” and “Excel for Dummies?”

Thankfully, there are good examples of documentation out there. Subversion, open source source-control software, has goal-driven documentation. It serves as a great example, in that the documentation (an open-source book, really) shows how to use subversion to achieve particular goals (how to migrate from another solution, how to restore my old file, etc), or how to set up subversion to operate in particular situations.

Goal-driven documentation effectively lowers the suck-threshold. It allows us to include more features (because we can more easily ignore them, and because we can see how and why we might use them, instead of just understanding how they operate). Goal-driven documentation also accelerates the user up the learning curve, allowing them to be productive far more rapidly.

Summary

Write goal-driven documentation. It helps users achieve their goals using the software. This creates more competent users more quickly. And it helps generate evangilists and salespeople within the user community.

Seilevel has a post that presents the top 10 signs that you should not pursue a career writing requirements, check it out.  Thanks Joy for the great article!
Our favorites:

#10 You cannot quickly understand new concepts

#9 You don’t have the patience to deal with customers

#4 You cannot form a mental model of all the pieces

Our take

Writing requirements is much more than taking dictation.  To develop great software, you have to develop an understanding of the needs of the customer.  From those needs, you have to synthesize a solution approach.  And you have to communicate that approach, both with customers (to validate it) and with the engineering team.  All of Joy’s entries (except the bonus #0 item) support this general framework.

We agree with Roger’s comments on the post that agile processes are not mutually exclusive to writing requirements.  Charles posted recently about the new product manager – implying that an agile product manager is different than a non-agile product manager.

There are many different agile processes, which use differing amounts of up-front planning, and differing formats for documentation.  Feature-driven development (FDD) does high level planning to understand the general approach of the product.  Details are then defined incrementally.  Incremental development works best when the most important stuff is worked on first.  This doesn’t preclude the need to communicate with customers and developers.  The fact that this communication happens incrementally doesn’t make documentation irrelevant.
The conversation about item #0 continues on Seilevel’s discussion forum, join in there, or add your thoughts here.

One of the ten big rules of writing a good MRD is writing passionate requirements. What in the world is a passionate requirement [they were all wondering]? When you believe in the product, are committed to the work, and aren’t bored, you can write passionately. The goal of a requirement is to create sustained understanding. A dry document can create understanding, but an engaging document will sustain it.

The Big Rule of Writing Passionate Requirements

From our previous article, Writing Good Requirements – Big Ten Rules:

Nothing great has been born from complacency, lethargy or mediocrity. When we are defining requirements, we must be passionate about what we’re doing. If we’re just going through the motions, it shows up in the writing. If we aren’t excited about a requirement, the problem is either with us or with the requirement. Either way, it won’t inspire the rest of the team to do something great.

Passion For The Product

When we are excited about our product, and believe in the value for our customers, we will write better. When we know that we are doing work that is worth doing, we approach it with that ‘extra something’.

Commitment to Writing

If we are just going through the motions, creating a document because someone told us that we have to, it will show. We need to appreciate that an MRD is the focal point for an understanding of our customer’s needs. We realize that our engineering team will be using that MRD as the source of their inspiration and actions. When the goal of our writing is to deliver understanding, we write differently than when our goal is to hurry up and move on to the next thing.

Personal Engagement

Few things affect the quality of writing more than boredom with the subject. If we are writing requirements for YACC (Yet another C compiler) and we’ve done it ten times before, we will lose something. Years ago I got some great advice – get out of your comfort zone.

Everyone has a comfort zone, where the work they are doing isn’t challenging. Immediately surrounding that comfort zone is the stretch zone where there is a little fear, growth and challenge. This is where we should operate. We don’t grow by doing the same thing over and over, in the same way. Outside of the stretch zone is the fear zone where we are operating as a fish out of water. If we’re unable to react, learn, cope and succeed, we’ve gone too far into the fear zone.

Complacency comes from boredom, which comes from spending too much time in our comfort zones. And complacency shows in the quality of our writing. We may write accurate, boring, easy to read and easy to forget requirements.

Out of Control

All of the factors above seem to be out of our control. We have employers, they give us assignments. We have to do what we’re told, even if we don’t believe in it. There are three things we can do.

The first is to find a way to believe in the product. Review the financial benefits, think about the improvements it makes for the users. We can find at least an element of what we’re doing that is relevant or significant. And we can focus on that.

The second is to find a way to focus on self-improvement. While we’re performing the job that we’ve decided isn’t worth doing, we can take on the meta-challenge of exploring it as a testbed for discovering better ways to do the job. How can we reduce the level of effort required to do the job well? Can we invent new approaches or master existing ones? We can focus on that.

The third is to think about why we have a job we don’t enjoy, doing work we don’t believe in. If we need the job, then we keep it. If we don’t need this job, we can look for another one that we will believe in. Or we can simply accept that our writing won’t be passionate. But hey, that’s no different than most of the stuff that we read.

Conclusion

Every job is done better when someone is passionate about it – writing requirements is no exception. Find a way to be passionate.

One of the ten big rules of writing a good MRD is writing atomic requirements. Just as verifiable requirements must be concretely measurable as having been met or not, so must atomic requirements. If a requirement has multiple elements that can be implemented separately, it is not atomic.

The Big Rule of Writing Atomic Requirements

From our previous article, Writing Good Requirements – Big Ten Rules:

Every requirement should be a single requirement. If we can say “Half of this requirement is implemented” then this needs to be two or more requirements. If a requirement read “Sales reps can manage their client list and generate custom reports” it expresses two atomic ideas (list management and report generation). Those ideas need to be separated

Determining Atomicity

There is a very simple test – can a subset of the requirement be implemented? Phrases like ‘the user will be able to X and Y‘ are tell-tale signs that a requirement is probably not atomic.

Why Atomicity Matters

Atomicity matters when developing a product roadmap. We can’t prioritize half a requirement for one release and the other half for another. Each requirement should be scheduled for a single release.

Testing of requirements should result in either a “pass” or a “fail.” A requirement should not partially pass its verification test.

Tracability of requirements is also simplified when each requirement is unique.

One of the ten big rules of writing a good MRD is writing verifiable requirements. Verification is both a function of having a precise goal, and having the ability to affordably measure the requirement. A precise goal is a verifiable requirement if we can clearly answer “yes” or “no” when asked if the requirement has been implemented. We also face the practical realities of being able to measure the results profitably.

The Big Rule of Writing Verifiable Requirements

From our previous article, Writing Good Requirements – Big Ten Rules:

We use a process that starts with market requirements, and then decomposes them into software requirement specifications. the market requirements must be written in a way that we can verify that the associated requirements specification will meet the market need.

Verifiable

We wrote previously that if a requirement can’t be tested, it should be rewritten. Roger Cauvin has recently reposted on testable requirements. Perhaps in anticipation of this article? :).

In the world of test driven design (TDD), the philosophy is to write the test first, and then write the code. We use a continuous integration approach to check in code regularly and run all of the tests as we go. When the test for a particular requirement passes, the code is done for that requirement.

We also get a big benefit in validating that we have delivered the right functionality to the customer. When we agree on the language of the requirement, we are also agreeing on the language of its verifiability.

Affordably Verifiable

With this big rule, we are assuming that we have already eliminated impractical or unattainable requirements.

Some tests are very expensive, or nigh on impossible. Roger alludes to this as testable in principle. Requirements should be testable in practice whenever possible. If a requirement can not be tested (“Must last 10 years”) in the delivery timeframe, we need to at least define a specific acceptance criteria – (“95% confidence in a cycle life of 10,000 cycles per procedure XYZ.doc”). This is the approach that Underwriter Labs uses for awarding UL certification to electrical appliances for safety.

Semantically, we can argue that this proxy criteria is in fact the requirement. It is the criteria by which acceptance is determined.

If the test is possible, but impossibly expensive, we shouldn’t run the test. If we can not agree on a practical proxy criteria, we are left with two choices. We can choose to not implement the requirement. Or we can choose to agree that the requirement is delivered when we say it is. Neither is a particularly good option, but the former is better than the latter, when it comes to maintaining a positive relationship with our customer.

Writing requirements without acceptance criteria introduces risk into our project. The last thing we want is to enter into a nitpicking discussion about what we have and have not delivered. We would much rather spend that time discussing what we can deliver next.

Conclusion

Write requirements that can be verified given the constraints of the project. Common constraints are time, money, equipment and expertise. Use language that makes the verification process explicit. The process of determining verifiability also dramatically helps eliminate ambiguity in our requirements.