Improvement Principles

I assembled this set of principles to guide me and others through the sometimes stormy times of change. To me, 'times of change' equals 'always'. If there's one common theme among all my different job positions and private challenges, it's the wish for improvement. Use these principles whenever you embark on a journey.

New Layout for ClearConceptualThinking.net

I finally found the time to change the layout of my blog. Hope it's much clearer now, improved readability. There are some issues with the way Google displays ads, but I hope to fix this within the next couple of days.
Let me know what you think, please!

Problem to Solution - The Continuum Between Requirements and Design

Christopher Brandt, relatively new blogger from Vancouver, Canada, has an awesome piece about the difference between problem and solution. If he blogs more about problem solving, and in this outstanding quality, he definitely is someone to follow.

While I do not completely agree with the concepts, I believe everybody doing requirements or design should at least have this level of understanding.

Requirements written that imply a problem end up biasing the form of the solution, which in turn kills creativity and innovation by forcing the solution in a particular direction. Once this happens, other possibilities (which may have been better) cannot be investigated. [...] This mistake can be avoided by identifying the root problem (or problems) before considering the nature or requirements of the solution. Each root problem or core need can often be expressed in a single statement. [...] The reason for having a simple unbiased statement of the problem is to allow the design team to find path to the best solution. [...] Creative and innovative solutions can be created through any software development process as long as the underlying mechanics of how to go from problem to solution are understood.

Which brings me to promote again and again the single-most powerful question for finding requirements from a given design: WHY?

Don't forget to have fun ;-)

Project management template for FREE download KOSTENLOSER Download: Projektmanagement Vorlage

Projects by the book or by the trenches?

The PRINCE2 project management standard by the OGC is a very practical piece of work. There is no obligation to do it by the book while you meet certain criteria. And it is supposed to be helpful, not an obstacle. I believe it is indeed helpful, and that is exactly why I based upon it the design of some quite central piece of paper document for some projects I work on, the Project Identification Document (German: Projektleitdokument).

I wanted to fulfill the following requirements:

• Mustn‘t be lengthy.

• Mustn‘t become shelf-ware.

• Must be easy to maintain.

• Must be interesting for the steering committee, the project manager and the project team.

• Must include everything relevant to guide projects of 5 - 20 week‘s duration.

• Mustn‘t shut off readers who are not familiar with PRINCE 2.

• Must facilitate checking defect density, i. e. number of defects per page.

• Must combine the PRINCE 2 Project Identification Document, Business Case, Project Mandate and Project Brief into one (1) manageable document (huh!).

I decided to design a standard document structure for one of my clients, along with guiding descriptions of every document section and a checklist for each section. As you might suspect from my background, my former work and my friends, I not only rewrote the respective PRINCE 2 product, but included my 12+ years experience with projects and some relevant pieces of good engineering, as taught by honorable Tom and Kai Gilb.

Out came the RTF template you can download for free from PlanetProject. Be aware that RIGHT NOW IT IS IN GERMAN only. If you would like to have it in English, please contact me and provide me with a good reason to work on the translation :-) (or maybe YOU translate it and provide it on Planet Project, too?)

Let me know what you think, please!

German Planguage Concept Glossary

I published a German Version of the Gilb's Planguage Concept Glossary on Google Docs. It comprises the 178 core terms of systems engineering and RealQA concepts that are part of the Competitive Engineering book. In the future I plan to translate the rest of the over 500 carefully defined terms.

The German words have been chosen to form a body of terms that is similar to the English original version, similar in coherence and completeness. Therefore, it is not a simple word to word dictionary translation. To the German reader, some of the words may seem to be translated badly. However, if you study the original glossary carefully, you will see that they make sense.

Furthermore, the terms have been tested in corporate practice and professional German conversation over a period of about a year. Most of them can be intuitively understood by Germans or German-speaking people; others need a quick look into the glossary definitions (which is something that is restricted to English-speaking readers ;-).

I'm happy to take your comments, critique and encouragement!

Why High-level Measurable Requirements Speed up Projects by Building Trust

(Allow 5 minutes or less reading time)

Stephen M.R. Covey‘s The Speed of Trust caused me to realize that trust is an important subject in the field of Requirements Engineering.

Neither the specification of high-level requirements (a.k.a. objectives) nor the specification of measurable requirements are new practices in requirements engineering after all, just solid engineering practice. However, they both are extremely helpful for building trust between customer and supplier.

The level of trust between customer and supplier determines how much rework will be necessary to reach the project goals. Rework – one of the great wastes that software development allows abundantly – will add to the duration and cost of the project, especially if it happens late in the development cycle, i. e. after testing or even after deployment.

Let me explain.

If you specify high-level requirements – sometimes called objectives or goals – you make your intentions clear: You explicitly say what it is you want to achieve, where you want to be with the product or system.

If you specify requirements measurably, by giving either test method (binary requirements) or scale and meter parameters (scalar requirements), you make your intentions clear, too.

With intentions clarified, the supplier can see how the customer is going to assess his work. The customer‘s agenda will be clear to him. Knowing agendas enables trust. Trust is a prerequisite for speed and therefore low cost.

“Trust is good, control is better.” says a German proverb that is not quite exact in its English form. If you have speed and cost in mind as dimensions of “better,” then the sentence could not be more wrong! Imagine all the effort needed to continuously check somebody’s results and control everything he does. On the other hand, if you trust somebody, you can relax and concentrate on improving your own job and yourself. It’s obvious that trust speeds things up and therefore consumes less resources than suspiciousness.

Let‘s return to requirements engineering and the two helpful practices, namely specifying high-level requirements and specifying requirements measurably.

High-level Requirements

Say the customer writes many low-level requirements but fails to add the top level. By top level I mean the 3 to 10 maybe complex requirements that describe the objectives of the whole system or product. These objectives are then hidden somehow implicitly among the many low-level requirements. The supplier has to guess (or ask). Many suppliers assume the customer knew what he did when he decomposed his objectives into the requirements given in your requirements specification. They trust him. More often than not he didn‘t know, or why have the objectives not been stated in the requirements specification document in the first place?

So essentially the customer might have – at best – implicitly said what he wants to achieve and where he is headed. Chances are the supplier’s best guesses missed the point. Eventually he provides the system for the customer to check, and then the conversation goes on like this:

You: “Hm, so this ought to be the solution to my problem?”

He: “Er, … yes. It delivers what the requirements said!”

You: “OK, then I want my problem back.”

In this case he would better take it back, and work on his real agenda and on how to rebuild the misused trust. However, more often than not what follows is a lengthy phase to work the system or product over, in an attempt to fix it according to requirements that were not clear or even not there when the supplier began working.

Every bit of rework is a bit of wasted effort. We could have done it right the first time, and use the extra budget for a joint weekend fishing trip.

Measurable Requirements

Nearly the same line of reasoning can be used to promote measurable requirements.

Say the customer specified requirements but failed to AT THE SAME TIME give a clue about how he will test them, the supplier most likely gave him a leap of faith. He could then either be trustworthy or not. Assume he decided to specify acceptance criteria and how you intend to test long after development began, just before testing begins. Maybe the customer didn‘t find the time to do it before. Quite possibly he would change to some degree the possible interpretations of his requirements specification by adding the acceptance criteria and test procedures. From the supplier‘s angle the customer NOW shows your real agenda, and it‘s different from what the supplier thought it was. The customer misused his trust, unintentionally in most cases.

Besides this apparent strain on the relationship between the customer and the supplier, the system sponsor now will have to pay the bill. Quite literally so, as expensive rework to fix things has to be done. Hopefully the supplier delivered early, for more time is needed now.

So...

Trust is an important prerequisite to systems with few or even zero defects; I experienced that the one and probably last time I was part of a system development that resulted in (close to) zero defects. One of the prerequisites to zero defects is trust between customer and supplier, as we root-cause-analyzed in a post mortem (ref. principles P1, P4, P7, and P8). Zero defects mean zero rework after the system has been deployed. In the project I was working on it even meant zero rework after the system was delivered for acceptance testing. You see, it makes perfect business sense to build trust by working hard on both quantified and high-level requirements.

In fact, both practices are signs of a strong competence in engineering. Competence is – in turn – a prerequisite to trust, as Mr. Covey rightly points out in his aforementioned book.

If you want to learn more on how to do this, check out these sources:

• Measurable Value (with Agile), by Ryan Shriver.
• How to rewrite a requirement / How to make it measurable (See a live example of a bad and a good high-level specification), by Tom and Kai Gilb.

You can also find related material on Planet Project:

• How to Specify High-level Requirements (aka goals).
• Requirements Hierarchies and Types of Requirements.

Why it is stupid to write specifications and leave out background or commentary information

Follow me on Twitter: @rolfgoetz

I wrote a set of rules over at PlanetProject that explain why it is a good idea to specify requirements (or designs) giving commentary or background information, and how to do it.

The article is based on a rather tiring discussion with a hired reqiurements specification writer in one of my projects. She seems to get defensive as soon as I suggest she should supply more 'context' for the readers of her request for proposal document.

More education please, this will bring us closer to the 'professional' bit of 'professional business analyst'.

Read the article here. Comments or addidions welcome! (It's a wiki...)

Refurbished: Non-Functional Requirements and Levels of Specification

follow me on Twitter: @rolfgoetz

After an interesting and insightful discussion with Tom Gilb and Sven Biedermann about one of my latest PlanetProject articles I decided to work it over. It is a how-to for a good requirements hierarchy. A good requirements hierarchy is an important prerequisite to a more-conscious and logical design or architecture process. This is because real requirements drive design, not designs in requirements clothes. (Thanks Tom for yet another clarification!)

It seems, in trying to write as short as possible I was kind of swept away from good writing practice and got sloppy with wording. I also found out that there is a philosophical, hence essential difference in how the process of 'requirements decomposition' can be seen.

1. One school of thought describes requirements decomposition as a process to help us select and evaluate appropriate designs.
2. The other school describes requirements decomposition as being a form of the design process.
   

Personally, I subscribe to the second meaning, because of a belief of mine: mankind is very used to solution-thinking, but very new to problem-thinking (Darwin weights in). So most forms of thinking, including requirements decomposition, are outputs of a solution-finding or design process. Or, as Sven put it, requirements decompostion is a shortcut to designing, where 'designing' takes on the meaning suggested by number 1 above.

However, it can be very useful to assume there actually is an essential and clear destinction between requirements decomposition and design processes. The point here is: you need to define it that way, then all is well :-) I didn't define it properly, and thus gave rise to many arguments written and exchanged.

Anyway, I hope the article now sheds even more light on the the constant quarrel about so called 'nonfunctional requirements', i. e. what they are, what they are for, why they are so sparse in the common requirement specification documents.

Most requirement specification document I see these days have lots of required functions, and few (if any) requirements for other attributes of the system, like all the -illities. AND many analysts (including me from time to time) confuse non-functional with scalar. Read the article on PlanetProject to learn more.

Atomic Functional Requirements

The discussion on shall vs. must at Tyner Blain , on which I have blogged recently, triggered me to wrap up what I have learned about atomic functional requirements over the years. 

See 3 principles and 4 rules on PlanetProject. Feel free to do responsible changes.

The article  explains how to write atomic functional system requirements so that the spec is easy to read, and ambiguity is kept to a minimum.

Note that it is NOT about the even more important (non-)functional user requirements here, in a sense of what a stakeholder expects from the system, which problems shall be solved, what shall be the inherent qualities of the solution etc. I do not intend to argue that any spec must include atomic, functional requirements. But sometimes setup is so that it must. Don't forget to establish the context first.

Now enjoy the article on how to write atomic functional requirements. Thanks for your comments.

Shall or must to markup mandatory requirements?

Generations of Business Analysts before me had to decide which auxiliary verb to choose in a mandatory system requirement. "Shall", like in "The system shall..." is probably most widely used in the English spec-writing world. But is it a good idea?

Scott Selhorst of Tyner Blain did some research using a novel research method on how ambiguous shall and must are. The bottom line: if for any reason it might not be clear to some reader that shall means mandatory, use must (consistently throughout the spec, of course, and put the convention in your requirements management plan).

I think the shall (as opposed to must) dates back to the old MIL-STD 498, or even DOD-STD 2167A.  And anyone who "grew up" BA-wise in the military or air traffic control fields like me, is very accustomed to the shall, and must might sound too harsh. But, hey, here's my favourite answer to that: "You're writing a spec, and you're not gonna win the literature Nobel prize for it!"

Interesting enough, as Scott points out in his article, in many languages other than English shall is not really used for the meaning of mandatory. In German, for instance, the meaning of shall is much closer to should than must.  And we all know what happens in waterfall projects when acceptance testing is due and the developer has implemented only half of the should requirements...

Writing Many High Quality Artefacts - Efficiently

I finished a process description on writing many artefacts, like use cases, requirements, book chapters, test cases, in high quality with the least effort possible. Please have a look, I'm eager to see your comments. After all, it's a Planet Project wiki article, so if you feel like it, just edit.

This, again, is on evolution, or learning by feedback. Makes heavy use of inspections. Inspections BTW, are one of the most effective QA methods known in software engineering history, according to metrics expert Capers Jones.

Update on Specifying Goals

I updated the Planet Project article on Specifying goals, using some of Tom Gilb's approaches and recent experience with the topic from one of my projects.

In this project, we struggled somewhat to explain to our subject-matter experts the importance of beginning with the (ultimate) end in mind. They thought they had to describe every little step, every button and every view of an IT application down to the smallest detail.

My favorite example was the following sequence (from a use case description), repeated a hundred times within the requirement specification:

1. User does some inputs
   
2. User "sends" the input, i. e. confirms his inputs
3. System checks inputs against rules X and Y
4. Systems shows an error message in case the checks fail.
5. ...

I finally got them with suggesting an alternative solution, roughly like this:

1. User does some inputs
2. (System has to make sure rules X and Y are not broken)

I guess the key was to make up a scenario which used quite a lot of sarcasm:

1. "I think I am an expert user."
2. "I do these simple inputs. Damn I'm good!"
3. "Now send the stuff to the stupid machine." *klick*
4. "Ooops ... What the ...."
5. "The stupid machine says I did it wrong?!"
6. "Why didn't it prevent me from doing it wrong, is there anything this machine is useful for?"

:-D

Use Case Content Patterns Updated

Martin Langlands incorporated "my" DESTRUCTOR pattern into one article, now version 2 of his Use Case Content Patterns description. Have a look here, the whole thing is easier to handle now.

Hint: Click 'files' at the bottom of the wiki page to see the pattern file. Sorry for the inconvenience!

Reviewing for content

Title: Reviewing for content
Type: principles
Status: final
Version: 2007-07-26
Gist: Conduct reviews in the right order.

P1: check formal characteristics
P2: only if the object is clean, it's useful to see if it's right

Clear Conceptual Writing

Title: Clear Conceptual Writing
Type: Process
Status: final
Version: 2007-07-15
Gist: To explain how to amplify skills for writing information texts (not fiction or poetry). You can apply it to the introductory or explaining parts of requirements and design specifications.
Source: Michael Covington and my own experience.

S1: Planning: Decide what to write about. It's not important to have a very clear idea about the subject yet. It will evolve.
S2: Planning: Decide, for whom you are writing. if you don't know much about your audience, go and find out first.
Note: Writing is about transferring ideas. Although it can be used as a thinking tool for yourself (like this blog), it was invented to express ideas for others to read. Keep in mind that your writing tells something about you, whether you make it easy for you or easy for your audience.
S3: Planning: Every section has a purpose.
S4: Drafting: Write everything down. So you don't have to juggle with ideas in your head.
S5: Drafting: Concentrate on the what, not the how. It's okay if only you understand what's on the paper.
S6: Drafting: Get to the point. Say the main point of every paragraph in its first sentence, then provide the reasoning that leads to the main point in the following sentences.
Note: Mark Twain once said "Establish the facts first! You can mess them up afterwards."
S7: Revising: Make your text as easy to read as possible. Use someone who does not know about the topic to find out if it's understandable. Your kids or your gandparents should be able to understand what you say.
S8: Revising: Shorten your sentences. Then shorten them again.
S9: Revising: Think of ways how your sentence can be misunderstood, e. g. by reading it aloud several times and stressing different words in each pass.
S10: Editing: Fix the grammar, spelling an punctuation.
S11: Formatting: Keep it simple and standard, avoid meaningless variation.

Principles of Clear Thinking

Type: Rules
Status: Draft
Version: 2007-12-20
Quelle: Principles of Clear Thinking. <- Blog on http://www.blogger.com/www.gilb.com 2007-03-27 (R1 to R10); rest: own thoughts
R1. You have to have a clear set of objectives and constraints, to evaluate proposed solutions or strategies against.
R2. You have to have a reasonable set of facts about the benefits and costs of any proposed idea, so that you can relate it to you current outstanding requirements.
R3. You have to have some notion of the risks associated with the idea, so that you can understand and take account of the worst possible case.
R4. You have to have some ideas about how to test the ideas gradually, early and on a small scale before committing to full scale implementation.
R5. If there are more than very few factors involved ( 2 to 4) then you are going to have to use a written model of the objectives, constraints, costs, benefits, and risks.
R6. If you want to check your thinking with anyone else, then you will need a written model to safely and completely share your understanding with anyone else.
R7. You will need to make a clear distinction between necessities (constraints) and desirables (targets).
R8. You will need to state all assumptions clearly, in writing, and to challenge them, or ask ‘what if they are not true?’
R9. You will want to have a backup plan, contingencies, for the worst case scenarios – failure to fund, failure for benefits to materialize, unexpected risk elements, political problems.
R10. Assume that information from other people is unreliable, slanted, incomplete, risky – and needs checking.
R11. Assume that you models are incomplete and wrong, so check the evidence to support, modify or destroy your models.