Each requirement you write represents a single market need, that you either satisfy or fail to satisfy.  A well written requirement is independently deliverable and represents an incremental increase in the value of your software.  That is the definition of an atomic requirement.  Read on to see why atomic requirements are important.

Atomic Requirements – Revisiting

As part of the ongoing series, Writing Good Requirements – The Big Ten Rules, I wrote about the importance of atomic requirements first in 2006.  That article touched on only one aspect of atomic requirements – being able to ask “is it done?”

Writing atomic requirements is important from two perspectives – delivering value to your customers, and operating efficiently.  You get benefits both operationally, and in how you are delivering value when you write atomic requirements.

Atomic Requirements Accelerate Value Delivery

In a recent article, I proposed methods for splitting user stories when they are too large to be delivered within a single Scrum sprint.  That article looked at ways to break up complete user stories (an agile requirement artifact, similar to a use case) that were already atomic, making them even smaller.  Think of that article as Atomic Requirements 301 – sort of an advanced class on splitting the atom.  There are opportunities to subdivide molecular requirements – those made up of multiple atomic goals – the topic of this article, which would be Atomic Requirements 101.

If you’re using an agile development process like Scrum, consider a user story like the following:

• As an online shopper, I need to find and compare similar products, a few times a year, so that I can make an informed purchasing decision.

The key element, from an atomicity perspective, is find and compare.  These are actually discrete user goals, although it may not be immediately obvious.  Rewriting as follows, will highlight this:

• As an online shopper, I need to find products and compare similar products, a few times a year, so that I can make an informed purchase.

Rewritten like this, find products and compare similar products are clearly different activities supporting different user goals.  They should be split into separate, atomic user stories.

1. As an online shopper, I need to find products, a few times a year, so that I can purchase desired products.
2. As an online shopper, I need to compare similar products when shopping online, so that I can make an informed purchase.

These two user stories can be delivered separately.  If this example were for B2B (business-to-business) eCommerce, the example would be different – because the online shopper is (often) not the right persona.  A typical situation in B2B is that one person will do the research to determine what to buy, and another person will make the decision of from whom to buy it.

This rule applies for non-agile requirements development as well – consider the following “BRD-style” requirement example:

• The system must record all purchases and submit them to the fulfillment system for processing.

Recording purchases and submitting them for processing are two different activities.  While they likely support the same goal, they may also support different goals and could be implemented separately.  Recording purchases is important not only for fulfillment, but potentially also for analytics.  Pushing data to a fulfillment system can be done in either a manual or automated fashion – providing a distinct cost-reduction opportunity.  To write these as atomic requirements, they must be separated.

1. The system must record all purchases.
2. The system must submit all recorded purchases to the fulfillment system for processing.

This example shows only the bare bones – there is more involved in writing either requirement, particularly around defining the non-functional requirements and business rules (see also: why you benefit when you separate rules from requirements, and the difference between business rules and business requirements) that affect and constrain each requirement.  This is easier to see when the requirements are atomic. These two atomic requirements may be rewritten as follows:

1. The system must record all purchases on the same day that they are created, recording information per [BR117: Purchase Data Rules].
2. The system must submit all recorded purchases to the fulfillment system for processing per [BR231: Fulfillment System Data Interchange Specification].

These additional constraints are not non-atomic additional requirements, they are constraints that specify how the system must perform the atomic actions.

The previous examples allude to another key benefit of atomicity – clean traceability.  Each requirement (or user story) exists to support one or more goals.  Requirements traceability can get complex, when many goals are dependent upon multiple requirements to be realized and many requirements enable multiple goals.  This approach to representing goal-decomposition (or user story decomposition) is critical to assuring that you are writing valuable requirements.

The simple version of traceability can be visualized with this view of structured requirements, presenting (and slightly extending) some of Karl Wiegers’ work on requirements.  If you’re doing any work in requirements of any kind, you need to read Karl’s stuff – his Software Requirements is a must-have.

This diagram makes it seem pretty straightforward.  Where it gets messy is when the multi-goal-per-requirement and multi-requirement-per-goal dependencies (that always exist) turn it from a simple tree into a complex graph.  Non-atomic requirements make that graph messier (a hassle, but not a problem)as each “requirement that is really multiple requirements” ads extra dependency relationships to your traceability model.  This becomes a problem, however, when you need to change.

Every project has implementation tasks that take longer than originally expected.  Using a time-box approach to managing the content of each release gives you a straightforward framework for determining how much stuff will be delivered in each release.  When you have to slip something, you have to revisit prioritization.  With well-defined requirements, each valuable requirement that could be delivered provides value by enabling users (or systems as users) to achieve a goal.  When you have to delay the implementation of a requirement, you delay the goals that it supports.

As soon as you realize you are considering delaying part of a requirement, that is a red flag that your requirement is not atomic.

Atomic Requirements Simplify Operations

Atomic requirements allow you to make these on-the-fly prioritization decisions with much better insight into the resultant delay in value.  This allows you to better manage communication with your stakeholders – validating that you are delaying the realization of the right goals.

The same benefits apply when originally planning your software iterations and releases.  Conceptually, you can imagine “scheduling” everything for the first release, immediately discovering that most things need to slip to future releases.  That’s how most* software projects really play out.

*There are times when you intentionally delay particular capabilities, based on external factors – market positioning, customer-adoption cadences, sales-team capacity (to absorb change), etc.

Conclusion

Writing atomic requirements helps you

• Organize and describe why you are asking the team to build what they are building, and how stakeholders will benefit from what will be built.
• Understand the assignable value of each requirement by maximizing clarity in the dependency tree – each requirement is in place for specific reasons.
• Communicate the relevance of each requirement to the implementation team – informing cost-benefit discussions around the inevitable schedule-change discussions.
• Test the deliverables – atomic requirements get graded as pass-fail, not “X% working.”

Attributions:

• Thanks clix for both “atomic” photos!

How do you approach starting a small requirements project as part of a large initiative within a massive enterprise? Do you boil the ocean? Your customer knows she needs “requirements” to give to her development team. She asks you – what will you deliver, and how long will it take? Great questions. If you have to write a statement of work, with time/cost estimates, and a list of deliverables – what would you do?

The Lay of the Land

Your IT director knows she needs something to give to her development and test teams. She’s looking to you to tell her what it is you need to deliver. Oh – and while it isn’t explicitly a constraint, her expectation is that you’re looking at something less than a couple of months of effort. To increase the pressure a little, she also tells you that her program will likely have a steady, ongoing need for requirements development – for now, she needs a “single capability” defined.

Her approach is really pretty rational. She’s rolling out a brand new initiative for the company. The initiative will drive tens of millions in profits for the company. There is a huge user base, there are stakeholders all over the globe, it is a “high pressure” environment – very visible internally, high external pressures, and there’s a palpable sense that continued employment is dependent on the success of the initiative.

There is an ocean of work involved in this particular initiative. Your director’s initiative needs to demonstrate momentum, so instead of boiling the ocean, she’s releasing new business capabilities incrementally. She’s working with the business stakeholders and customers to define “what first”, and then she’s working with internal teams to enable those capabilities one at a time. Each business capability is being treated as a distinct program – distinct funding, staffing, and timing. Sort of an “enterprise agile” – certainly an incremental approach.

The capability that she needs next (she has already prioritized it as “next” for the initiative) is also needed by other directors, for other initiatives. The enterprise IT folks intend to leverage the capability across many different programs and areas of the business. Each program has common and distinct needs, and different timing objectives. There are many moving parts involved in defining this capability across a multi-billion dollar enterprise.

Your mission is to figure out how best to validate your customer’s approach, identify what she needs, and estimate what it will take to make it happen – given the above environment. Do you try and boil the ocean, defining the requirements for the business capability across all the initiatives? If not, how do you define and manage deliverables for this one program?

One At A Time

There’s an interesting dynamic that comes into play when working with teams across and within an enterprise architecture. You have to think about the big picture (the ocean) in order to really understand things. At the same time, if you try to accomplish all of the needs of the disparate teams (boiling the ocean) at the same time, you will fail. Each group has its own dynamics, politics, deliverables, hangups, issues, and pet “favorite features.” If you try and tackle all of them at once, you will get mired in the bog of analysis paralysis and never make forward progress.

The best way to knock down all the dominoes in this case is to knock them down one at a time. Think of it as sequential product releases, each one targeted at a different market segment. Because that’s really what it is. As you build out a business capability (like “provide hosted service X”, or “sell products online”) for each program you are identifying a different set of internal stakeholders, end users, and often, delivery and test teams. They are independent projects that happen to share a lot of goals.

Dominoes make for a great analogy, because although you start out by knocking down the first one, you knock it towards the second one, with the intent of knocking them all down eventually. The more you understand about the other dominoes, the better a job you will do in knocking down the first one. But you have to focus on the first one first. The other knowledge provides context, and hopefully understanding that leads to insights.

Knock down the first one first.

How Much to Do?

You can approach this top-down (as we normally do with structured requirements), or bottoms-up. Either way, you end up with the same answer. We’ll work backwards in this article – since we’re identifying the deliverables, not creating them.

• Software Requirements Specification (SRS). We already know we need this – because the development and test teams at the company expect to work against an SRS. If your company uses something else to communicate requirements to development and test, substitute that artifact here.
• Fact Model and Glossary of terms.  Explicit agreement about language and terms is critical to avoiding confusion and ambiguity.
• Use Cases. The requirements in the SRS are defined to support use cases and goals. So we need use cases. The team you are working with, and the complexity of the business needs / processes will influence the format that works best.
• Actor Hierarchy and Personas. You have to identify the actors by role, and the personas that describe them.
• Business Requirements Document (BRD). Describes the goals of the business stakeholders.
• Vision & Scope Document. Describe the vision for your program, and its scope. Especially valuable in avoiding ratholes in this environment – be articulate about what you are not doing. Set expectations that the second domino is second – only the first domino is first.

You can reverse this list to create a top-down set of deliverables: Vision & Scope Doc, BRD, Actor & Persona definitions, Use Cases and SRS.

And Estimating…

The devil is always in the details when it comes to estimating. How long will use cases take? How many interviews will you have to do, and do you need to travel to do them? And a hundred more questions.
We aren’t trying to tackle the estimation details here – too many project specific variables, and as I just read somewhere, “estimating is more of an art than a science.” Although you can apply some science to expose and mitigate the risks around your estimates by using PERT analysis.

But now you know what you should deliver, and what you now have to go estimate.

What is the right level of detail for writing requirements? What about for writing specifications (functional, non-functional requirements, etc)? The answer is that there is no one answer. But there are guidelines, and reasons to write more detail, or less detail – for any given product or project, and any given team. The reason we write requirements is so that they can be read. Understanding the readers is the key to determining which details to include in the requirements.

Requirements for Agile Teams

Steve Johnson and I had a great discussion this morning about his webinar from last week, Extreme Product Management. Steve’s presentation is really good, and worth a listen to answer questions about how to combine product management and agile development teams to achieve market-driven product successes.

As part of a follow-up, Steve and I got to talking about how much to document for agile teams. A few hours later, he shared a slide with me that he had put together, that provides a great visual of the concept. In short, the more your team knows about your domain, the less documentation details they require to be effective.

[click for larger version]

Generalizing The Relationship

Steve’s slide is well designed for the “who do we need to be effective with an agile process?” question. And it can also lead us down paths that consider outsourcing, in-sourcing, off-shoring and co-location of development teams. That isn’t necessarily where we want to take the discussion for this article.

What Steve’s slide (not from the webinar, by the way) illustrates is that different audiences respond differently to different processes. From an understanding of how agile processes work, we can extend this idea – we need to write differently for different audiences.

Generally speaking, the more you know about a domain, the fewer the words needed to convey a concept (or requirement) with precision. Without using jargon, you can still communicate more concisely. Remember, though – the goal is clarity, not brevity. For example, it is much easier to describe the concept of drafting when speaking to a racing fan. [Note: drafting is riding or driving close behind another competitor, in order to benefit from the reduced aerodynamic drag.] When someone already knows what drafting is, providing instructions on how to do it is easier than if they do not.

Use Case Details

At this point, you may be thinking but there is a right level of detail for use cases. Alistair Cockburn talks about the level of detail for describing use cases in Writing Effective Use Cases. Jeff Patton has a good article explaining Cockburn’s levels. Cockburn uses a metaphor of elevation:

• Cloud Level – very high level summary
• Kite level – summary
• Sea level – “single sitting” task descriptions
• Fish level – small tasks that add up to valuable tasks
• Clam level – very small details that make up small tasks

Cockburn suggests writing at three levels – summary, user goal (sea level), and sub-function (fish) levels.

The authors of Patterns for Effective Use Cases present an interesting pattern – EverUnfoldingStory (pattern 4.5, p102). They point out that different readers of use cases need different levels of detail.

An architectural analysis may only need very high level details of the use cases. Other readers of the use cases may need to understand the interplay of use cases at a more detailed level. And individuals may need to understand a particular use case in even more detail, while only needing a higher level understanding of other use cases.

The suggested pattern is to use multiple layers of use cases that can be “drilled down” into to get more detail, and can be rolled up (and hidden) to obscure detail when it isn’t needed. The clearest way to achieve this is with subordinate use cases.

This seems like conflicting advice – write for your audience, and write for all audiences.

Supporting Details

The language you use should be adequate for anyone who has a reasonable level of understanding of the domain. For example, in a business application, it would be appropriate to use language like “The system will report the net profit of the sale.” It would also be appropriate to specify a business rule that “All companies with EBITDA below 5% be treated as high-risk investments.”

When your team needs it, you should provide explanations and definitions in a glossary of terms. The level of domain expertise determines how much explanation you need to include. As a product manager or business analyst, you ideally should not have to document the definition of “net profit” and EBITDA. You aren’t teaching a course on financial accounting, you’re specifying a product. You should be able to reasonably expect that team members understand, or can easily find definitions for these industry terms.

You might need to define (or link to a definition of) HHI, or other more esoteric terms. You can’t expect your developers to have MBAs. You absolutely need to define any terms that are specific to a single customer (product managers cover your ears). For example, the method of allocating overhead. As a rule of thumb, management accounting terms would need definitions, as they are often interpreted differently by different companies. You have to find a balance, by understanding who is reading the documents, as to where you draw the line.

In practice, make sure that you have budget and time allocated to deal with this. When your company leans more towards the “development factory” model – treating people who sling code as a commodity, you will need to allocate more time and effort towards education. Recognize that you will be articulating business requirements, in a language that requires some understanding of business terms. If you can use that knowledge to influence how you staff the project, great. If you don’t plan ahead, you might get lucky – but more likely, you’ll find yourself with scope creep, or missed estimates.

How Have You Dealt With This?

I’ve been on projects where the implementation team had deep domain expertise. The communication was very efficient. I’ve been on projects where the team was able to very quickly gain that expertise. Those teams needed some early education, but very quickly became efficient. And I’ve been on projects with teams that had no experience in the domain. It was like teaching them a new language – and unfortunately, we did not expect to have to spend time on that education. And it delayed the project. Eventually, they became conversant in the domain.
The best practice I walked away with was to not clutter the artifacts (directly) with these definitions, but to identify and link to reference materials, and an easily searchable glossary of terms. This allowed team members to drill down when they needed to, without being distracted by wading through unneeded information when they didn’t.

We would love to hear about situations like this that you have run into, how they caused problems, and how you solved them. Maybe there are better ways to address this stuff.

Almost a month ago, we published an article titled Broken Requirements Ecosystem. That article built on a discussion thread at Seilevel. Since that time, the original thread has grown, and a new one has been spawned at the Catalyze site.

In short, the question was asked on the Seilevel forum- why are specs sometimes ignored by developers, and four possible reasons were suggested.  We followed up with our view, and the discussion picked up again, this time at Catalyze.

1. Original discussion thread on Seilevel’s forum: Reasons Reqs Go Unread (Discussion from 19 Jun to 26 Jun )
2. Article at Tyner Blain: Broken Requirements Ecosystem (Written on 21 Jun, Discussion to 26 Jun)
3. Thread spawned on the Catalyze forum: Broken Requirements Ecosystem (Discussion from 23 Jun to 15 Jul)
Note – the dates above for each article/forum-post are as of right now. People have submitted 23 comments across the articles, showing a lot of good insight from many different perspectives. Developers, product managers, project managers, stakeholders – lots of great comments!

Even if you read our article before, go back and follow the discussions again – starting with Seilevel’s article, and progressing to ours, following up with the conversation at Catalyze.



]]> http://tynerblain.com/blog/2007/07/17/ignoring-requirements-take-two/feed/ 2 http://tynerblain.com/blog/2007/06/21/broken-requirements-ecosystem/ http://tynerblain.com/blog/2007/06/21/broken-requirements-ecosystem/#comments Fri, 22 Jun 2007 04:13:00 +0000 Scott Sehlhorst http://tynerblain.com/blog/2007/06/21/broken-requirements-ecosystem/



There’s an interesting thread on Seilevel’s requirements forum about why developers don’t read the specs and how to fix this problem. Sometimes the developers throw away the requirements. And that’s bad. But it is a symptom. Something is broken at a higher level.


The Forum Conversation

In short, the conversation is asking why some developers don’t implement code that meets the specifications. There are several possibilities identified in the discussion:

• The developer is too busy to bother with specifications.
• The developer is too smart and knows better than the spec-writer.
• The developer doesn’t understand the specifications.
• The developer pre-judges that the specifications are probably bad.

Why Write Specifications?

Taking a step back to think about why we write specifications is like trying to understand what causes the common cold – instead of trying to prevent symptom X.

The philosophy of the five why’s is a problem solving approach designed to get to the root of a problem. We can twist it to force ourselves to look at the bigger picture – and maybe gain some insight from looking at this discussion in a broader context.

1. Why write specifications? So that the developers will know what to build – and testers know what to test.
2. Why does it matter what the developers build? So that we can deliver what we promised to our customers.
3. Why do our customers care what we deliver? Because we have promised to solve their problems.
4. Why is solving customer problems important? Because customers have goals, and problems thwart those goals.
5. Why are customer goals important? Because customers are in business for a reason – and those goals are an articulation of that reason.

OK – so we have some context – we are trying to solve a particular problem (or set of problems) for our customer(s). To keep the writing simpler, we’ll talk about one problem / goal for one customer. But the ideas apply to multiple customers and goals.

Our customer has a strategy (or reason) which drives the creation of a goal. Our customer chooses to use our software as a means of solving the problem that prevents them from otherwise achieving that goal. We make choices about how to solve that problem, and articulate that solution approach as a specification. And our team creates a solution that meets the specification – and tests to confirm that it meets the specification.

Software As Fast Food

Jonathan Babcock wrote a thought-provoking article about how McDonald’s is one of the highest quality restaurants. Without going off on a tangent about fast food, one conclusion we can draw is that McDonald’s does a fantastic job of implementing according to the specification. Their employees don’t ignore the procedures (the spec). People can debate about the quality of the spec, but you can’t argue with the execution of the teams in the restaurants. When I was in Kuala Lumpur a few years ago, the McDonald’s french fries tasted just like the ones here in Austin, and the ones in Paris, and the ones in Manhattan. They may even be zealous in how well they follow the spec.

Why don’t the people working in the restaurant ignore the spec? Chris the fry cook likes his french fries extra crispy – crispier than the spec calls for. He knows they are better this way. Why doesn’t he cook them a little bit longer? The customers would certainly be happier. Evan is a brand new cashier. He doesn’t know that the unsold hamburgers need to be thrown away after an hour of sitting under the heat lamp. How is it that Evan never gives me a two-hour-old burger?

McDonald’s has a working Ecosystem. You may argue that they are addressing the wrong customer goals – or have chosen a bad approach to meeting those goals. But you can’t argue that their execution is bad. They absolutely follow the spec.

Why Isn’t McDonald’s Ecosystem Broken?

Do they do an adequate job of training new hires? Is there sufficient oversight during the orientation period of those new hires? Do they properly set expectations for the employees? Do their employees understand the importance of their decisions? [As a side note - I have been yelled at about french fries when I worked at a restaurant in high school - but it wasn't a McDonald's - it was a 4-store private chain. A restaurant equivalent of a startup]

Maybe they’ve automated and constrained the process so much that a monkey could do it. They have definitely done some of that – the fry cook no longer eyeballs the amount of french fries to put in each basket – a robot dispenses the proper amount. And a timer determines the proper length of time to fry them – while a thermostat regulates grease temperature. But you still have to rely on the people to know when to drop the fries to meet demand. And you have to rely on the people to pull the fries out when the buzzer goes off (according to the spec). You have to rely on the employees to destroy excess food instead of selling it – even when that is more convenient. And do you know a teenager who prefers “the right way” to “the easy way?” And yet, it still seems to work.

I believe that the specs are good. And I suspect that the managers stress and reinforce the importance of following the specs. And I believe there is sufficient training to assure that people know how to follow the specs. And when someone doesn’t know how to do something, there is always someone there to help. It is a culture of “ask for help when you need it.”

What Can We Learn From McDonald’s?

There are two important elements, and they are addressed very differently. First, it is critical that the specs be good. Writing good requirements is important. Second, the culture must be such that people realize that they are required to follow the specs. How you deal with that will vary from team to team, and person to person.

If you don’t set the expectation that the specs be followed, why would you expect them to be followed? And if the specs are bad, that’s another problem entirely. But you should encourage people to help you fix the specs – not ignore them.



]]> http://tynerblain.com/blog/2007/06/21/broken-requirements-ecosystem/feed/ 3 http://tynerblain.com/blog/2007/04/25/apr-mixing-it-up/ http://tynerblain.com/blog/2007/04/25/apr-mixing-it-up/#comments Thu, 26 Apr 2007 01:46:58 +0000 Scott Sehlhorst http://tynerblain.com/blog/2007/04/25/apr-mixing-it-up/


With a definition of the important use cases for our agile project, we can move to the logical next step – which is what exactly?

Prototyping.

Depending on which discipline is dominant in the project approach, the next step could be to define the functional requirements (or specification) that support the use cases. Or it could be to take user-centric approach to prototyping interface elements. Or it could be developing an understanding of the domain model that will drive the behavior of the site.

Functional Prototyping

Ruby on Rails (Rails, for short) makes rapid prototyping of the “under the hood” stuff appear to be very quick to develop. And Rails separates the presentation from the logic with a model-view-controller approach to code structure. From the reading I’ve done about Rails, the next step needed to get an interactive prototype is to define the representational model.

In the better object oriented programs I’ve worked on in the past, the underlying representation matches the user’s conceptual model as well as possible. This will be challenging to not confuse the two and expose the implementation to the users. I’m not sure what differences will exist between them, we’ll see when we explore this. Creating a UML static diagram of both will help.

UI Prototyping

Creating some mockups of the user interface and documenting some design elements and interaction ideas will help here. I started that process last night and have the first initial thoughts drawn on paper. I will scan those in and post them as paper prototypes.

Documenting Requirements

If we were using a purely structured requirements approach, we would create an SRS at this stage. In conjunction with this prototyping approach, we will capture those same requirements. The requirements will be defined in the context of the individual use cases that we are focusing on for the first release. Don’t forget to vote on the use cases if you haven’t already.

Iteration



This process will be iterative or concurrent. The goal is to get enough of an understanding of the design to create an initial prototype.



]]> http://tynerblain.com/blog/2007/04/25/apr-mixing-it-up/feed/ 4 http://tynerblain.com/blog/2006/11/23/fifteen-ways-to-shut-down/ http://tynerblain.com/blog/2006/11/23/fifteen-ways-to-shut-down/#comments Fri, 24 Nov 2006 02:58:08 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/11/23/fifteen-ways-to-shut-down/



[Updated Below] There are 15 ways for someone to shutdown a laptop running Windows Vista. This adds unwarranted complexity to our software. How can we avoid the same problem in our software?

Hat Tip

Joel (on Software) has an article where he lambastes the Vista team for providing 9 different ways to stop using the computer. Add in the hardware options on the laptop (like Fn F3), and closing the screen down or hitting the physical power button, and you get to 15 different ways to shut down.

Inevitably, you are going to think of a long list of intelligent, defensible reasons why each of these options is absolutely, positively essential. Don’t bother. I know. Each additional choice makes complete sense until you find yourself explaining to your uncle that he has to choose between 15 different ways to turn off a laptop.

Joel Spolsky

Make Everybody Nobody Happy

Joel posits that the unreasonable number has grown out of the desire to make everybody happy. We know that too many features makes everyone unhappy. This bloated list of choices is just one manifestation of too-many-features, and it doesn’t make anyone happy.

Inadvertantly Causing The Problem

It is pretty easy to imagine how we might inadvertantly cause this problem.

A structured requirements approach allows us to track and manage different requirements, as well as the implementation of those requirements. In Joel’s example, imagine requirements like the following:

• User secure the computer in order to walk away from it without other people getting access.
• User can shut down the computer such that it will stop consuming power.
• The computer will support rapid switching from one user to another.

Each requirement could drive an independent solution approach. As Joel points out, each requirement, evaluated in isolation, may lead to a different solution. The problem is that we are finding local optima, and not looking at the problems introduced by the complexity of supporting all of these solutions.

Avoiding This Problem

How can we avoid this sort of problem in our own product development? A holistic view of the proposed solution is required to assess if there are too many features. Prioritization of those features will help us reduce the number to a reasonable level.

Incorporating elements of interaction design into our solution approach may be the best way to do this (short of abandoning a structured requirements approach).



Each of the shutdown scenarios leads to a functional requirement. Each element of program design leads to one of the many ways to shut down or lock or restart the computer. Addressing the personal goals of each persona provides us with a cross-feature, holistic perspective. If our target audience includes Joel’s uncle, then we can make sure that our design approach accounts for the appropriate level of complexity and choice.

[Update]

Moishe Lettvin, one of the developers on the shutdown team for Vista, formerly at Microsoft, has written an article about the organizational and situational challenges faced by the team. He titled the article The Windows Shutdown Crapfest. That should give you a feel for how the now-Googler feels about the experience. There were 43 people involved, and they spent over a year. And the source code control system was frightening. Check out the comment thread on Moishe’s article too – it includes comments from other Microsoft and knowledgable anonymous people. Hat Tip to Scoble. Also, a followup from Moishe.
Summary

Multiple requirements can lead to multiple, locally-optimized solutions or features. A holistic view needs to be taken to assure that we aren’t introducing too much complexity with these variations of similar features. Interaction design gives us a big-picture perspective to make sure we aren’t making our software too hard for our target users to use.



]]> http://tynerblain.com/blog/2006/11/23/fifteen-ways-to-shut-down/feed/ 10 http://tynerblain.com/blog/2006/10/24/another-use-for-why/ http://tynerblain.com/blog/2006/10/24/another-use-for-why/#comments Wed, 25 Oct 2006 03:35:20 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/10/24/another-use-for-why/



“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.



]]> http://tynerblain.com/blog/2006/10/24/another-use-for-why/feed/ 5 http://tynerblain.com/blog/2006/10/04/writing-for-the-purpose-of-reading/ http://tynerblain.com/blog/2006/10/04/writing-for-the-purpose-of-reading/#comments Thu, 05 Oct 2006 05:03:36 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/10/04/writing-for-the-purpose-of-reading/



The reason we write is so that someone can read it in the future. Duh. When we’re writing requirements documents, or documenting processes, how often do we stop and think about who will be reading our documents? We need to make sure our writing will be easy to read for our audience.

Writing As Marketing

Sam Decker makes a great point about how marketing should use the language of the customer in his recent article. This is actually the 11th in a great series on marketing, if you aren’t reading Sam’s stuff, you should be.

Hit the bulls eye by writing in the language of the customer. To use the same terms, phrases, and straight-forward speak that a customer might use when asking someone else about your solution (and of course, they probably didn’t use the word ‘solution’)!

Sam Decker

Applied To Requirements

Product Managers and others in the “requirements space” all create requirements documents. We create different documents to achieve different goals. It isn’t enough to target our communication content for our audience – we also have to think about the vocabulary we choose to use.

As requirements people, we tend to be precise in our use of language – avoiding ambiguity at all costs. When offshoring, or dealing with multi-cultural teams in general, we also have to understand when terms have different meanings for different people. We also have to watch out for terms that have symbolic meaning, that suffer from varying interpretations.

This precision can come at a cost if we don’t take into account the domains of expertise of our readers, and the terms that they know. As Sam points out, we want to use the language of our audience when describing something.

This can be challenging for pedants like us – when there is a perfectly good, albiet obscure term, why replace it with a sequence of more common words? It goes against our nature. We want concise documents. But clarity (for the reader!) should not be sacrificed for brevity.

Applied To Process Documentation

In addition to documenting requirements, when we are working as business analysts, we also usually have to document existing processes. This is really only true for migration projects, but those represent almost all single-customer projects.

We should make sure that our documents use our customer’s terms when documenting these processes – not our own terms. The responsibility is ours to translate from the single-customer language to the multi-customer concepts.

Process documents are reviewed initially by business owners, and are eventually consumed by systems analysts or implementers. Maybe a glossary of terms is required to help a multi-customer implementation team deploy enterprise software for a client. The documents developed for, and validated by the customer should use the language of the customer.

Applied To Communication In General

When we’re in meetings, having conversations, writing emails, or in any other way communicating with our clients, we need to use their language. Product managers should come equipped with a universal translating device. While an initial conversation may start with industry-standardized terms, as client-specific equivalents are identified, the product manager or analyst should immediately create a substitution and use it in all future communication.

We also have to think about the backgrounds of our audiences. Here are a couple stupid things I’ve said in recent meetings with business owners (who have backgrounds in finance and the insurance industry):

• “From the flow, you can see that the process recurs, and will do what we need.” Translation: The process repeatedly calls itself until it reaches a decision point that forces it to stop. At least I didn’t specify that the process was tail-recursive.
• “The decomposition of the work is straightforward, we just establish the proper quanta for breaking down the work in each area”. Translation: Break down the work into reasonably sized chunks. What the hell was I thinking?

Pretty much everyone groans when a smug consultant mentions a priori conclusions about prioritization, or an “obvious” algorithm. I’m sure there were a couple groans when I talked about quanta. The use of recursion is even worse – to a programmer, it has a precise meaning. To a non-programmer, it simply means repitition. The dictionary example uses “The cancer recurred” – and I’m sure it doesn’t mean that the cancer cells were attacked by cancer. I actually introduced ambiguity by using a term that some people would find to be more precise (the process was walking down a hierarchical business-data-structure, processing elements along the way).

Conclusion

Thanks Sam for pointing out that we need to speak in the language of our customers. We can extend this idea to make sure we use words within the vocabulary of our audience as well.



]]> http://tynerblain.com/blog/2006/10/04/writing-for-the-purpose-of-reading/feed/ 4 http://tynerblain.com/blog/2006/09/12/insight-into-tdd/ http://tynerblain.com/blog/2006/09/12/insight-into-tdd/#comments Wed, 13 Sep 2006 04:55:20 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/09/12/insight-into-tdd/



James Kovacs shares a great insight on software testing and the software testing process. His epiphany about test driven development makes it obvious to all of us why this technique is so powerful.

TDD

Test driven development is an approach to software development where you write the tests first, and the code second. This sounds ludicrous at first, but it really does work. Here’s James’ epiphany on the subject (emphasis added).

I didn’t understand why TDD practitioner were so zealous about writing the tests first. Why did it matter? I thought it was to ensure that some project manager doesn’t try to shave some time off the project by cutting the unit tests. Then I started doing some reading about TDD, poking around, asking questions, and trying it out myself. I discovered the real reason for writing tests first is that TDD isn’t about testing code, it’s about designing code.

A Tale of Two Epiphanies: TDD and Mocking, James Kovacs

These tests are unit tests, and they are black-box tests (or at least should be black-box tests – read James’ article).

Works Great With Structured Requirements

Not only is this a great way to approach design, but it is a great way to coordinate software development with structured requirements. A well-written requirement describes a need without specifying design. This description then works like a black-box contract. The implementer then must do something that meets the specification given. As James points out, TDD is very effective at creating black-box tests.

This makes sense, when you consider the outside-in approach that comes from starting with requirements. This outside in approach leads to API decisions (for a program or module or method). The API has to support all of the required possible inputs and outputs. Once an API is written, tests can be written.

Best Applied As Part Of Continuous Integration For Larger Teams

All of the tests will fail (because the code hasn’t been written). Then the implementer will write code until the tests pass. Using a continuous integration approach is a very effective way for entire teams to do this simultaneously on larger projects.

Faster Processes

We can also validate the design for completeness prior to creating the implementation. We can compare the generated APIs (and their rationalizations) with the software specification (or application requirements, or FRS… see alphabet soup article). This allows us to address some refactoring needs before the code has been implemented – saving time and money.

Conclusion

Use TDD as an outside-in approach that assures that the delivered software will meet the objectives of the requirements specification. It also saves time and money by supporting validation in advance of implementation.



]]> http://tynerblain.com/blog/2006/09/12/insight-into-tdd/feed/ 0 http://tynerblain.com/blog/2006/07/17/communicating-intent-with-implementers/ http://tynerblain.com/blog/2006/07/17/communicating-intent-with-implementers/#comments Tue, 18 Jul 2006 04:14:58 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/07/17/communicating-intent-with-implementers/



Giving a functional spec to developers and testers is not sufficient for creating great software. To a developer, a spec is only the what and not the why. And for a tester, the software requirements specification is neither. Use cases provide the why that explains the intent of the system for the implementation team.

Background

We started a series of posts exploring why we apply use cases as part of product management, identifying 8 goals for which use cases are relevant. That series post contains links to detailed articles on each goal as we write them over the next weeks. Bookmark it and come back to it to see the puzzle come together.

We recently wrote an article, Communicating Intent With Stakeholders, that shows how use cases are consumed from the perspective of users and customers, or stakeholders. In that article, we showed a diagram that compares the different perspectives of the software development artifacts.



Use cases fall in the “requirements” row of this diagram. The requirements row represents the documents used to articulate the value of a proposed solution. The article, Requirements Documents – One Man’s Trash, provides a more detailed explanation of these differing perspectives.

Communication of intent with the implementation team is different than it is with stakeholders. The implementation team represents people performing one of two activites: building the solution and assuring the solution is correct. Different teams will staff these roles differently. Some teams will have separate QA organizations, and others will rely upon the developers to also be responsible for quality.

Development

Some people will argue that a development team only needs the specification to create software. That’s absolutely true in a turn-the-crank situation. And its very common in many outsourcing arrangements that use a low-level outsourcing model. The downside of these approaches is that we hamper our developer’s ability to apply their creative skills to creating innovative solutions.

By providing developers with an understanding of why they are being asked to implement software that conforms to a specification, we get the opportunity to benefit from their feedback. A free electron developer [scroll down to the People section of this article for a definition] may have an epiphany about a significantly better way to solve the problem. Wthout insight into the intent of the software, that star developer is hamstrung.

Quality Assurance

Quality assurance personnel (QA) are responsible for assuring that the software does what it is supposed to do. While developers can write whitebox tests to assure that their code behaves as anticipated, QA has to rely on blackbox tests to assure that the intent of the system is being met. This requires that QA understand the intent of the system.

Blackbox tests are generally described as a series of user actions (or the automated equivalent), usually referred to as a script. Each script, to be as valuable as possible, should be designed to mimic what a user would do when trying to achieve a particular goal. Functional requirements are written to support use cases. While we can write short tests that validate individual functional requirements, these tests would really only be scriplets, because they do not represent an entire user session.

Good tests are atomic. When a test fails, we want to be able to say that test X for functional requirement Y failed. And scripts should be written with these atomic assertions in mind. There are two reasons, however, to group these assertions together into scripts that match use cases.

First, when using a structured requirements approach, a single functional requirement may support multiple use cases. Developers will want to know which functional requirement failed, and the context in which it failed. However, when we communicate project status with stakeholders, we will be talking to them in the language of use cases. Providing an association between functional requirements, their tests, and the relevant use cases makes this much easier.

Second, because these are blackbox tests, they are written without insight into the implementation by definition. It is possible that a particular functional requirement will pass all of its tests when performing one use case, but fail them when performing another. We can use pairwise testing or other techniques to find these circumstances by brute force. But we can also re-use the assertions (an individual test of a functional requirement) across multiple scripts (use cases).

Summary

Members of the development and quality organizations benefit from understanding why they are implementing or testing a particular functional spec. Use cases provide them with that context. Use cases are also the artifacts most easily understood by all team members.



People in all three groups can easily consume use cases. If an individual is unfamiliar, a quick lesson on how to read use cases can help.



]]> http://tynerblain.com/blog/2006/07/17/communicating-intent-with-implementers/feed/ 0 http://tynerblain.com/blog/2006/07/13/foundation-series-data-dictionary-definition/ http://tynerblain.com/blog/2006/07/13/foundation-series-data-dictionary-definition/#comments Fri, 14 Jul 2006 03:55:44 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/07/13/foundation-series-data-dictionary-definition/



What is a data dictionary and how is it used when communicating and managing requirements?

Definition

A data dictionary is a collection of the definitions of the structure of information that is relevant to a set of requirements. That’s a lot of words for a simple concept. We need to know (and constrain) a set of information about some business element when managing our requirements. We use a data dictionary to define what that information is, and any constraints on how it must be used.

Viewing The System

When using object oriented analysis (OOA) as part of defining requirements, we represent business concepts as objects and processes. For example, an order management system might define orders as having line items and customers. We can represent that information graphically with a UML diagram like the following:



In prose, we could also capture the same information as follows:

1. The system shall include a representation of customer orders.
2. Each order will have a single associated customer, and each customer can have multiple orders. Note that a customer is not required to have any orders.
3. Each order will have at least one, and possibly multiple line items. Each line item is uniquely associated with a single order.
4. Each line item represents a single product. Note that a product is not required to be represented in a line item. A product can be represented in multiple line items (even within the same quote).

While this diagram tells us about the structure at a high level, it doesn’t tell us enough information to go implement the solution. What exactly is a line item? What information does it contain? And what format must that information be in?

A Dictionary Entry

We could create a data dictionary entry for the line item object as follows:

Line Item

A line item represents a portion of a customer order that describes a product being ordered, as well as the quantity of that product being ordered. Each line item must include the following information:

• A reference to the product being ordered, using the product ID per constraint X1. [Note, the constraint is imposed by the existing product data management system, with which our software is required to integrate.]
• The quantity of the product being ordered, where the quantity is a positive integer. [Note, we would include a maximum value, if there were a constraint imposed by some other part of the system.]

Note that we have not specified that a line item includes a price. It is very likely that a line item would have a price, but we would be specifying implementation details if we did. Pricing may be done per product, or may be unique for each product for any given customer. Discounts may be applied based upon quantity of products in a line item, or dollar amount for an order. Discounts may be applied based upon all products ordered by a customer over a period of time. These different possibilities are a function of the requirements of the system.

When those business requirements are defined, they will dictate the ownership of properties by business objects. With that information, we can include the data as appropriate. For example, a list price property may be defined for the product object, or a customer-price may be defined for a line-item as a function of (product, quantity, customer). We would add that data as part of the business modeling. Note that this is a description of the problem domain, not a description of the implementation.
Another Data Dictionary Example

Here’s an example of a “Customer”

A customer represents the business or person for whom an order has been placed. Note that all character fields are to be represented in unicode 4.1.0 or later per corporate policy ABC. A customer has the following information:

• Name. 50 characters representing the name of the customer.
• Shipping Address 1. 100 characters representing the first line of the address to which all customer shipments are made.
• Shipping Address 2. 100 characters representing the second line of the address to which all customer shipments are made.
• Shipping Country. 50 characters…
• Billing Address.
• Customer Contact.
• etcetera.

This list is intended to show all of the elements of information that must be present in the “customer object” to support the requirements of the system.

Further Reading

Joe, at Seilevel wrote a post back in March with a good explanation of data dictionary entries. As Joe points out, requirements can drive the need for specific information.

For example, my business users have told me that the number of decimal places of each weight value tracked by the system is very important for monitoring and reporting. It stands to reason that other objects and attributes might require the same level of specification. If you figure it out once, you can use it in many places.

Barbara, at B2T Training points out the importance of understanding the details of the data for a system. She also touches on the value of having that information in a separate document.

Many BAs document data as part of the business process or part of the Use Case. Our recommendation is that you document data in a separate part of the requirements package because it is often used in multiple places.

Usage

A data dictionary should be defined as a repository of all data definitions like the examples above. Those examples should be referenced in all requirements documents that rely on the defined objects. Requirements documents should not specify the content of the objects, they should defer to the referenced dictionary entries.

Some projects, especially migration projects, have many constraints tied to data formats and structure. These projects will have extensive data dictionaries, and multiple references to entries throughout the requirements document. Other projects will have far fewer constraints on data formats, but will still have explicit structural definitions for business objects (like our line item example).

- – -

Check out the index of the Foundation Series posts which will be updated whenever new posts are added.



]]> http://tynerblain.com/blog/2006/07/13/foundation-series-data-dictionary-definition/feed/ 2 http://tynerblain.com/blog/2006/06/15/writing-passionate-requirements/ http://tynerblain.com/blog/2006/06/15/writing-passionate-requirements/#comments Fri, 16 Jun 2006 04:07:13 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/15/writing-passionate-requirements/



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.



]]> http://tynerblain.com/blog/2006/06/15/writing-passionate-requirements/feed/ 9 http://tynerblain.com/blog/2006/06/14/writing-atomic-requirements/ http://tynerblain.com/blog/2006/06/14/writing-atomic-requirements/#comments Thu, 15 Jun 2006 02:29:45 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/14/writing-atomic-requirements/



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.



]]> http://tynerblain.com/blog/2006/06/14/writing-atomic-requirements/feed/ 0 http://tynerblain.com/blog/2006/06/13/writing-verifiable-requirements/ http://tynerblain.com/blog/2006/06/13/writing-verifiable-requirements/#comments Wed, 14 Jun 2006 03:32:58 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/13/writing-verifiable-requirements/



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.



]]> http://tynerblain.com/blog/2006/06/13/writing-verifiable-requirements/feed/ 0 http://tynerblain.com/blog/2006/06/12/writing-unambiguous-requirements/ http://tynerblain.com/blog/2006/06/12/writing-unambiguous-requirements/#comments Tue, 13 Jun 2006 03:25:58 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/12/writing-unambiguous-requirements/



One of the ten big rules of writing a good MRD is writing unambiguous requirements. Ambiguity is a function of communication. The writing can be generically ambiguous, or ambiguous to the writer. A requirement could be precise in intent, but ambiguous in interpretation by the reader. Understanding our audience is as important as precision in language. We write unambiguous requirements because misinterpretation of requirements is the source of 40% of all bugs in delivered software.

The Big Rule of Writing Unambiguous Requirements


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

A great requirement has a single interpretation. A good requirement has a single reasonable interpretation. As part of our development process, we will use listening skills like active listening to make sure that our engineering team understands the requirement we intended to write. The better the requirements, the less expensive and risky this communication process will be. Writing unambiguously is critically important when using outsourcing models that limit our interactions with other team members.

Ambiguous to the Writer

We introduce ambiguity with imprecise language. Using shall instead of should is one of the first things people suggest (or require!) when writing requirements. [Added 2010.08.17 - shall is ambiguous too - use must!]  Red flags are also raised with words like can and might. Marcus wrote a good post about vague requirements language

What do the terms: user-friendly, flexible, easy-to-use, fast, and intuitive mean to you? Do you think these terms mean the same thing to someone else? Generally, no!

from Speculative and Vague Terms

These are examples where the language is ambiguous, both to the writer and the reader. Any uninformed third party could read these requirements and identify the amiguity in the language. This makes these mistakes easy to catch – all that is required is a good working knowledge of the language.

Ambiguous to the Reader

Even precisely written, grammatically correct prose can be ambiguous to the reader. This ambiguity can come either from lack of expertice with the language, or from incompleteness of the requirement.

Language Ambiguity

With the ever-increasing outsourcing of teams, we have to think about writing requirements for outsourced team members. When we use a complete technical outsourcing model, we have to consider the possibility (or certainty in some cases) that the primary language of the readers of the MRD is not the language it is written in. Making a document easy to read (short sentences, common words) can be at odds with making the language of the requirements precise.

Some good research on vocabulary size data for comprehension of english can be found here. The average native english speaker knows 20,000 word families. With a vocabulary of 5,000 english words, only 98.5% of the words in a given text will be understood. 5,000 words is a lot for a speaker of a second language (3,000 words is considered a working knowledge).

An analysis of the reading-level at which a document is written can be helpfull in identifying if the language is likely to be challenging for readers with limited vocabularies. The Gunning-Fog Index provides a measure of the education level at which a text is written.

Incompleteness Ambiguity

When the language is both precise and understood, we still face challenges in ambiguity by failing to provide all the information. When we find ourselves wanting to say “That was implied, you should have known that!”, we are still being ambiguous. Clarity exists not only in language but in intent. Should the reader assume that when we specified user-authentication and role-based functionality that we intended users to have roles? If we specify that the best-matching search results must be presented within 1 second, is it ok if the rest of the results are presented later? And how many of the best-matches must be found?

Writing requirements like this is definitely a risk, and probably ambiguous. If we have a history, a rapport, and synchronous feedback cycles with the readers of the document, this may not be vague. We may be able to rely on them to assume the same things we assume. The language in the document may be serving effectively as shorthand for this communication. If we are working as a team with a shorter history of working together, this almost certainly will not communicate what we intended. There is also a risk of going too far.

Conclusion

Writing unambiguous requirements requires us to write complete requirements. It also requires us to use precise language that communicates information across domains to our readers. To determine the right level of effort, we need to monitor the effectiveness of our communication, and balance that with the amount of time we can afford to dedicate to word-smithing instead of other product management activities.



]]> http://tynerblain.com/blog/2006/06/12/writing-unambiguous-requirements/feed/ 5 http://tynerblain.com/blog/2006/06/09/big-ten-rules-writing-consistent-requirements/ http://tynerblain.com/blog/2006/06/09/big-ten-rules-writing-consistent-requirements/#comments Sat, 10 Jun 2006 02:25:21 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/09/big-ten-rules-writing-consistent-requirements/



One of the ten big rules of writing a good MRD is writing consistent requirements. Consistency within an MRD has two dimensions that are important to requirements – logical consistency and grammatical consistency. There is also the element of writing an MRD that is consistent with other documentation – external consistency.

The Big Rule of Writing Consistent Requirements


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

Pragmatic highlights that the requirement must be logically consistent with the other requirements in the document – no overlaps, no contradictions, no duplications. This is certainly the most important point of consistency.

There is also benefit to consistent writing in an MRD. We can use templates to provide a consistent framework, but more importantly the prose needs to be consistent. This consistency makes it easier on the readers.

Logical Consistency

Logical consistency within an MRD requires us to pay attention to what we’re writing. Applying the big rule of atomicity (one market requirement per written requirement) simplifies this quite a bit. The biggest source of duplication comes from writing requirements that involve involve two related ideas. The duplication is obvious when we find it, but with very large systems (and documents) it can be easy to overlook.

Avoiding contradictions can be harder. We might write mutually exclusive requirements, or requirements that are independently attainable, but that neither can be realistically attained if they are both implemented. For example, we could write a requirement that specifies near instantaneous search results, and we could write a requirement to include insanely large amounts of data (like the call logs for all customers of a telecom provider for all time). While this is possible, it might not be attainable for our team, who could easily implement a relatively innefficient search algorithm, or who could set up a very large data store.

Grammatical Consistency

Use of templates can provide a way to make individual requirements consumable. They also help with the learning curve of people who regularly read the MRD – they set expectations, and when followed, make scanning of the documents more efficient. The problem with templates is that not every requirement fits the same mold, and it can be cumbersome to squeeze the requirements into a stock format.

External Consistency

An MRD is one document in the flow of requirements from market needs to product. Often, an MRD is used to drive the creation of a PRD, and it captures a vision for the product and explanation of the relevant market research and how it applies to creating our product. Occasionally, only one of the MRD / PRD documents is created. Either a Software requirements specification (SRS) is created directly from the MRD, or the PRD is created in conjunction with other strategic documents (vision, roadmap, market research). Different companies use different approaches, and there isn’t a generic best answer.

Regardless of the mix of documents we use, the documents exist to support each other. Each document is a targeted expansion of the higher-level document. We need to make sure we write each document at the same level of detail, and each supporting requirement at a level of detail “one step” beyond the requirement it supports.

This approach allows readers to know where to find the big picture view, and where to find the devil in the details.
Conclusion
We have to make sure we don’t contradict ourselves logically. We need to manage the level of detail that we use consistently within and across documents. And templates can help us with using a consistent structure within a document.



]]> http://tynerblain.com/blog/2006/06/09/big-ten-rules-writing-consistent-requirements/feed/ 0 http://tynerblain.com/blog/2006/06/08/writing-complete-requirements/ http://tynerblain.com/blog/2006/06/08/writing-complete-requirements/#comments Fri, 09 Jun 2006 04:58:07 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/08/writing-complete-requirements/



One of the ten big rules of writing a good MRD is writing complete requirements. We identify problems and opportunities in the market. We determine that one of these problems is valuable enough and practical to implement. Then we have to write the requirements, and make sure that the requirements will completely solve the targeted problem.

The Big Rule of Writing Complete Requirements


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

Simply put, if the requirement is implented as written, the market need is completely addressed. No additional requirements are required. When writing a specification, we may use decomposition to break individual requirements into more manageable, less abstract criteria.

No Silver Bullet



Unfortunately, there is no silver bullet that we can apply to make sure that a requirement is complete. The best we can do is explicitly check it for completeness. And there’s no gaurantee that we will be right – our analysis is only as good as we are.

Pragmatic Marketing has a coffee mug that helps us with this.



Their message is simple – use data to support everything from valuation to prioritization to completeness verification. Don’t use opinion.

Imagine the following market problem for a mom-and-pop exterminator:

We aren’t making enough money from quarterly treatments. Our technicians are completely booked, but they spend at least three hours a day driving from job to job – double the industry average. Our prices are competitive, and our costs are in-line with the industry. We need our technicians to perform more treatments per day. Spot checks of a few previous schedules revealed that travel time could be reduced by 70% if we reorganized the treatments to minimize travel time.

We could write a product requirement as follows:

We need software that determines the better routes for our technicians each day. The optimal route is the one that requires the minimum travel time between each location, and between the office and the first location. Our software must generate routes that are 50% better than our existing process. Our dispatcher will be able to use these routes to plan each technicians schedule for the day. Note: The dispatcher will communicate the daily schedule to each technician at the beginning of each shift.

Analysis

We have data. Prices and costs are reasonable, but profit is unacceptable. Technician efficiency is the identified culprit. We’ve written a software requirement that should provide us with an improvement. We’ve assessed the potential value (50% reduction in travel time) and validated that it is feasible (70% reduction for manual spot-checks). We’ve even established critera for testability of the requirement (50% improvement over existing process – we can use historical data to validate the software solution).

Completeness

Well, it looks complete.

In our example, however, we didn’t do enough research. If we implemented software that provided more efficient routes, we would not get more efficient route execution – here’s why:
Additional research reveals that 80% of the time, the technicians have to return to the office to pick up more treatment chemicals because they didn’t bring enough with them for the whole schedule, or they have to cancel the last job of the day to account for drive time to return left-over chemicals to the office. The technicians can not take the pesticides home with them, and try to avoid a return trip to the office at the end of the day. If they use up all of the chemicals, they can drive directly home from the last appointment.

We need to add a requirement that our software also include planning of the amount of chemicals to take on each day.

Conclusion

Completeness comes from analysis. And our degree of completeness comes from the quality of our analysis. There is no silver bullet, we just have to think. Remembering to validate completeness, and base our decisions on data gets us half-way there, but we have to get ourselves the rest of the way there.



]]> http://tynerblain.com/blog/2006/06/08/writing-complete-requirements/feed/ 1 http://tynerblain.com/blog/2006/06/02/writing-design-free-requirements/ http://tynerblain.com/blog/2006/06/02/writing-design-free-requirements/#comments Sat, 03 Jun 2006 05:15:50 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/06/02/writing-design-free-requirements/



One of the ten big rules of writing a good MRD is writing requirements that do not specify design. How do we specify enough detail to be actionable without constraining the engineering team? How do we trust our developers to do the right thing?

The Big Rule of Avoiding Design-Agnosticism


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

Generally, a requirement should not specifiy any of the implementation choices. From a product manager’s perspective the requirement is the ‘what’ and the spec is the ‘how’. To a system designer or architect or lead developer, the requirement serves as a ‘why’.

Reviewing the Flow of Requirements from the Market to the PRD


Product managers begin by identifying a need in the market. The need can either be a problem that needs solving, or an opportunity that awaits a solution. Pragmatic Marketing teaches (and we agree) that people will pay more to solve problems than they will to address opportunities. Our previous article on innovation touches on the demands to reduce costs (address pain) that overshadow the attempts to seize new markets (opportunities).

Once a problem has been identified in the market, the product manager will capture it in an MRD. The MRD provides context for the entire project, and may include a vision statement and a product roadmap as well. This vision is built upon the identified market needs.

A PRD identifies those market problems that are to be solved within the scope of a product. The transition from MRD to PRD is an ideation process. The product manager must determine which problems are worth solving (high enough ROI) and which problems should be solved earlier or later. The PRD captures a definition of the problems to be solved with this product.

The software requirements specification, or SRS, is created from the PRD. This article is focused on the MRD, so covering the flow through the PRD is where we will stop.

To Act or Not To Act



Alas poor Product Manager. [Ed: silly idea]
Actionable Requirements

The MRD identifies the market problems with enough information for someone to ask “How should we solve this?” The creation of the PRD is the step where we say “We solve this one with our software, but not that one. And do this one first.”

For an MRD to be actionable it needs to provide insight into the problem, without assuming a particular solution approach. Software solutions are specified in the PRD. Here are a couple examples.

Bad

• Our premium skateboards are losing market share.

Good

• Our premium skateboards are losing market share to Tony Hawk’s new high-end board. We advertise in the same places, and have similar prices. Tony introduces a new limited edition board every month, which quickly sells out. His boards stay on the cutting edge of truck and bearing design, but his boards have half the life in tests that ours do.

Why is Good Good?

With the comparative information, we know that our competitor has differentiated technology, and we have better quality. This market research data (not opinion) allows us to make decisions about how we want to characterize and address the solution. We have not specified a solution.

Bad

• We need to update our social-networking website. Furl allows people to give ratings not just of linked pages, but also of other people. Furl is doubling in traffic every quarter while we have no growth. We need to add people-rating to meet our goal of doubling traffic every six months.

Good

• Our social-networking site is not growing as fast as we want. Furl is doubling in traffic every quarter. They allow people to ratings to other people, not just to linked pages like our site. We need to at least double our traffic every six months.

Why is Bad Bad?

There is an implicit assumption in the bad example – that adding people-rating capabilities will improve our traffic. The MRD should not include solutions, only identification of the problems. We might decide that we think people-rating is irrelevant, and that we will solve this problem with a marketing program. The research data is important, but the conclusions should not be drawn in the MRD.

Conclusion

Don’t draw conclusions in the MRD. Provide the data only. Conclusions represent design.



]]> http://tynerblain.com/blog/2006/06/02/writing-design-free-requirements/feed/ 2 http://tynerblain.com/blog/2006/05/31/writing-concise-requirements/ http://tynerblain.com/blog/2006/05/31/writing-concise-requirements/#comments Thu, 01 Jun 2006 04:06:38 +0000 Scott Sehlhorst http://tynerblain.com/blog/2006/05/31/writing-concise-requirements/



One of the ten big rules of writing a good MRD is writing concise requirements. We have to minimize the amount we write to avoid information overload. We also need to make sure we write enough to get the message across. How do we strike the balance?

The Big Rule of Brevity

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

Easy to read and understand. If only it were that easy. For whom is it easy to read? A market requirements document (MRD) is written for several different people on the team. It provides a vision of what problems our product solves. It provides clarification to the implementation team. It also sets expectations with stakeholders. Different people on the team have different domains of expertise – we have to write requirements that are easily understood by all of them.

The primary goal of concise writing is to improve communication and retention of ideas. The goal is not to save time. It takes more time to write less. Trust me on this.

How do we confirm effective communication?

Confirm Personally

The only way to confirm that the reader of a document understood what the author wrote is to ask him. “Did you understand?” doesn’t work. We have to create a feedback loop where the reader can give us confirmation that they understood. Teachers would do this in the essay portion of a literature exam – “In your own words, what did the author mean by…?”

We can get this feedback by directly speaking with the reader and using active listening skills to confirm that the reader understood the key concepts. The goal isn’t to correct the person’s understanding during the conversation. Rather, any misunderstanding is a “bug” in the documentation. We use those gaps to update our document, and then validate that the changes are understood.

Confirm Indirectly

A less effective technique, but one that might be required when working with a geographically distributed team is to infer levels of understanding by reviewing the output of the reader. We can potentially confirm that the reader understood the requirement by validating ‘the next step’ in the process. We can confirm that a business analyst understands the market requirement by validating the software specification that she creates. If the spec ‘completely covers’ the requirement, and does not introduce new ideas, then we know that the requirement was understood. If the spec is inadequate, then it may be due to mis-communication, or lack of competence.

As product managers, we aren’t in a position to validate the designs created by the implementation team, so this approach generally will not work for validating a spec. We may have the skills (perhaps we previously were developers or designers), but we should not try and do this – we risk getting caught in the weeds.

Improving Our Writing

• Requirements documents need to be scannable, much like web pages or articles. Readers need to be able to refer back to a particular requirement repeatedly to understand how to validate their work. We also need to be able to verify the requirement. Use of lists and short paragraphs help with referenceability and scanning.
• We have to be on the lookout for repetitive content within a requirement. The repetition at best is hard to read, and at worst is self-conflicting.
• We can include examples. Examples are often very illustrative of an idea.
• We can include OOA diagrams. Entity-relationship diagrams, when the reader knows how to interpret them, are very effective both for precise documentation, and for concise documentation. Remember that we are diagramming the problem, not the solution.

Conclusion

Write no more and no less that you have to. Confirm that the readers understand what you intend.



]]> http://tynerblain.com/blog/2006/05/31/writing-concise-requirements/feed/ 1