Category Archives: Writing

Tutorials and suggestions on how to improve your writing. Primarily focused on writing requirements, use cases, and other artifacts of importance to business analysts and product and program managers.

Pictures and Ideas for Powerful Whitepapers

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.

Continue reading Pictures and Ideas for Powerful Whitepapers

Effective Status Reports

forecast

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.

Continue reading Effective Status Reports

Defining Problems With Cause And Effect Diagrams

fish head

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!

Continue reading Defining Problems With Cause And Effect Diagrams

Requirements Writing Style and Synonyms

roses, by any other name

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.

Continue reading Requirements Writing Style and Synonyms

Why Separate Rules from Requirements

separate but equal

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.

Continue reading Why Separate Rules from Requirements

Writing Stylish Requirements

big ten rules

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

buzzhead

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.

Logical Requirements

spock

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.

Pairing Business Analysts

petronas towers

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?