Skip to main content

Author: Marcos Ferrer

Dear 007 Why Do I Hate Documenting Requirements

Dear 007:

Why do I hate documentation? Every time I turn around, stakeholder ideas, preferences and decisions change. Now they want to change the name and content of half of the processes already modeled plus the related specs.

This affects over 300 pages of documentation including 17 Visio Use Case Diagrams, 12 Word Smart Art flowcharts AND requires some adjustments to the grouping and order of steps among use cases.

Every change to the model requires me to re-do a dozen drawings and find, search and replace dozens of references, some “acronymized”, some spelled differently, and some in (rats) pdf images, which don’t search. Don’t even talk about “re-tracing” new relations between requirements, that is a separate spreadsheet that I intend to hide so they don’t make me do it over.

How can I un-wreck the reqs docs without becoming a wreck? Change management isn’t the answer here. Most of the changes are important improvements, and quality modeling will weed out the rest. It was the quality of the currently documented model that stimulated the improvements, but success has ruined the model.


Reed O. Rexorbust

Dear Reed O.

Your experience is quite normal for the document based requirements you describe. Your business stakeholders may not care – they are focused on the latest topic, and don’t read detailed models anyway, and “know what they mean” especially if it isn’t written down. Your implementation and operations stakeholders WILL care – wrong “detail”, wrong solution.

Two recommendations:

1. Follow BABOK requirements categories – don’t mix stakeholder wants with business / strategic requirements and be sure to segregate solution / design requirements from transition requirements (a discussion suitable to self-train a little on this topic can be found at this link).

2. Don’t store requirements in documents, generate documents from requirement stores. Below is a sample (very simple) use case model generated with an extremely affordable tool – Sparx Enterprise Architect. It is like VISIO on mega-steroids, a true database of requirements objects that can be turned into the latest document at the push of a button (and, you know, choose templates, give the document a name, blah blah). There are other requirements tools, but I bought this one because it did not require the whole enterprise to agree; Sparx EA can function as a “personal” BA tool, like VISIO, but it produces high-quality requirements documents on demand with minimal manual intervention. It is also a collaborative requirements work environment, but that is a DIFFERENT discussion.

As proof of concept, I invite (defy, even) my brilliant readers to comment on what is missing or just wrong in the model below. Go big (describe new effects or even new image instruments) or go small (I hate the blue titles).

I will incorporate ALL suggested changes into the model so that ALL may see the impact of the changes AND the ease with which the tool allows me to deal with said changes.

Management, of course, reserves the right to prioritize and evaluate changes for implementation, but we will simply capture them for discussion next month.

1 Imagenator – LightDrum – Use Case Model

Copyrights 1991, 2015 Marcos Ferrer

1.1 Vision

It is up to the Imagineers of the world to develop this tool, whether called LightDrum, Imagenator, C-ROD or whatever finally flies. The idea is inevitable, the implementers are not, so let’s get started thinking.

The primary architecture will be the visual language (see Appendix for specifications). Vusic (its invention) the key abstraction. Without limitations, visual performance may be spectacular (think psychedelia of all kinds or videos playing behind musicians). Such performances typically accompany live music yet typically lack nuance, improvisation, emotion and interaction that ARE characteristics of the music being accompanied (unlike the performance “Hydrogen Jukebox” by Phillip Glass, or the sophisticated uses of lighting in theater and film, or the singer / dancer duo Xia).

Music is typically limited to some scale of sounds with some mathematical relationship. Any sound might be a part of a piece of music (jackhammers, water running); sound, like image, has no trivial limits. AND YET, when music is not TOO inclusive, we often enjoy it most (pieces that have no key are interesting, pieces that move between keys are more interesting, and pieces that do their keys movingly are most beautiful of all. Music has the advantage of limitations – the musician can work with a finite set of auditory signals to create beauty in real-time.

Imagicians in today’s world must select from EVERY POSSIBLE IMAGE (or at least every possible image generator) for a visual performance. This is NOT real time, like music, and requires far more effort, planning, and execution. Imagicians can’t just sit down and “play image” to express beauty in most cases. Even those like myself who have written and used software to perform live imagery, have felt the narrowness of the expression instead of the universality of same.

This hasn’t necessarily hurt image performance. The biggest yell I ever heard for a single, simple “live” image was the crowd’s scream at a Grateful Dead concert for the “dancing bear.” It danced a goose-step march, mostly out of time to the music, but got superstar applause. The appearance prompted the scream, after a little bit it was dumb and boring, and needed to go away. The visual performer at the time could not have been less interested in improving the bear’s performance under live control (hi, Fritz, remember me?).

And I could not have been more interested. Twenty years later, no one is even working on this that I know of, even though image performance is BOUND to become a great art form in the future.

If you are an Imagineer that believes that live, visual, vusical language based performance is an idea whose beginning has come (we will not end it, just like the lute did not end music), this is the life project for you.

Anyone from: ?

Or anyone who finds this history interesting: ?

1.2 Develop / Deliver / Enhance LightDrum Architecture / Software / Hardware – Strategic Approach

It is premature to SPECIFY a specific development process, and yet the idea of continuous integration is hard to ignore. If every code check in every day leaves us with working software, the image instrument can only grow.

The idea is to provide reliable sensor polling “infrastructure” for developers to “plug-in” their contributions to the visual language. This approach allows wide collaboration while maintaining a central source of quality control. If the world helps build this, the world may adopt it as a seed, or even a standard.

2 Primary Use Cases

2.1 Primary Use Cases diagram

Use Case diagram in package ‘Primary Use Cases’


1.1 Configure (Tune) LightDrum


2.3 Configure LightDrum_ActivityGraph


2.4 Play LightDrum_ActivityGraph


3 Appendix – Visual Language Reference

Available on request – trade secret.

So there you have the model – what’s your feedback?  Can you break the analyst?  I say I am NOT scared of the re-do, of wrecked requs and will not bust.  Prove me wrong with your comments below.

Thanks for reading!

BA-elzebub’s Glossary – The D’s

Be sure to chip in some D’s of your own, and a few E’s for next time!

D’Oh!:  The perfect attitude to take around any requirement error.  Makes it easier to fix, especially when the BA takes it for the team.

The next three items were inspired by Ronald 2015-05-19 18:35

Data:  The facts collected in the current system – usually the root cause of the need to replace the current system.  

Data, Also:  The opinion of the sponsor about the facts and how they should be discussed by the BAs, regardless of the facts.  

Data, Choose Yours Wisely:  Grasshopper.

Data Dictionary:  One aspiration of certain social climbing Thesauri.  

Thanks to Rich Larson of the BA Times 2015-05-19 15:57

Data Model:  An activity that most BAs would prefer to the information designs they actually do.  Not all BAs – you know who you are.

Data Base:  Piccolo’s Prom dream?

DARPA:  Defense Advanced Research Projects Agency recently known for Driver Accident Reduction Pending Automation.

Inspired by Joe 2015-05-19 14:40

Deadline:  A term of little meaning or consequence.  A date picked with hope, in case hope really matters.

Thanks to to Rich Larson of the BA Times 2015-05-19 15:57

Decision:  A behavior performed too fast or too slow by somebody not yourself.

Thanks to Rich Larson of the BA Times 2015-05-19 15:57

Diagram:  What we turn to when words fail us.  Do not confuse with ViagraMan.  Not funny, unless you do it instead of me.

Decision Tree:  Analytical technique complicated enough that the sponsor might get away with the weights selected for the branches, without anyone actually checking them.

Defect:  Error NOT of design, BUT of execution, as in “That defect killed the wrong person.”

Delay:  A period of time required to complete a project, regardless of the deadline. 

Delete, CTRL-ALT:  Also know as the “three finger salute”, it is a chance for your PC to die with its re-boots on.

Delete, Create, Read, Update: Analysis technique not also known as DCRU.

Delirium:  See deadline.

Deliverable: An object substituted for results.

Deming, Edward:  Guru of quality, singlehandedly responsible for YOUR preference (yes, you do) for Japanese cars.  Famous saying:  “Defects are not free.  Someone makes them, and gets paid for making them.”

Devil’s Dictionary:  A far better read than BA-elzebub’s poor efforts, by a delightful writer named Ambrose Bierce.  Get a copy if you can.

Dirty Write:  A form of preserving data integrity equivalent to “What the heck” (see Heck in this edition of the Glossary).

Disaster Recovery Plan:  NOT “Don’t let the door hit you on the way out…”

With more thanks to Ronald 2015-05-19 18:35

Discovery:  The phase when the project team works out which requirements weren’t.

Disinclination:  One of many common reactions to working with requirements as in “It’s too much trouble to climb this inclination of mine.”

Disk Drive:  Trip taken when the operations manager realizes that the only good backup is on her personal computer at home.

Disk, Floppy:  A condition associated with OLD disks.Diskette:  A cure for floppy disks.

Distracted Driving:  Human driving.

Distributed Computing:  A form of missed requirement, as in “I thought they were doing that over there on the other system.”

Domain, Business:  The primary activities of the business, as in “Spying on do customers is do main business of FaceNet.”

Domain, Subject Matter Expert(s):  Do main person(s) whose best thinking is responsible for the current state.  Also known as “do box” one must “get out of”.

With thanks to steve 2015-06-25 06:45

Dormant:  State of requirements or expectations that sleep soundly during elicitation and suddenly wake up hungry for BA-er meat during acceptance testing or thereafter

DoS:  Denial of Stakeholder, as in “You can’t talk to THEM.”  

Dragon:  Adjective describing most meetings, not to be confused with:

Dragoon:  The goon causing the meeting dragon.

Drive, Shared:  Good luck, I’m sure its out there somewhere.

Duct Tape (aka Duck Tape):  One of the big two cures in engineering.  Unfortunately, it is completely completely useless in software engineering.  You know, “If it’s stuck, spray it with WD-40, if it’s loose…”

With more thanks to Steve 2015-06-25 06:45

Dundant: The first time something occurs.  For all the rest of the times, see redundant (and Einstein’s definition of insanity). Redundant things are superfluous, while dundant things are merely fluous.

Duplication of Effort:  A real “boy” story, used by IT to avoid extra stress (hey, give them more budget and employees before you complain too much).  Example from boy:  “Why do I have to pick up my room?  It will just get cluttered again!”  Example from IT boys:  “You shouldn’t implement that software – we will just have to replace it when we fix everything!”

Dubious Philosophy:  I once read that it was Socrates who said “To be is to do”, and Plato who said “To do is to be”, but we had to wait for Sinatra to say “do be do be do”.

Dumb Ideas:  There are none – leave your comments and thoughts below 🙂

Dear 007, Am I Finished?

Sometimes I get questions from BAs and PMs, and when I can’t answer them, I pass them on to CBAP 007. With an IIBA license to drill, no business analysis issue is too big or too small for this experienced professional. Here is one from July 2015:

Dear 007:

My project manager tells me to “finish the requirements”, but no matter what I turn in, she says it is not finished. When I ask what else she wants, she says she wants everything. When I suggest that everything costs infinity, she says I have an attitude.

She is right (about my attitude). What should I do to “finish” the requirements?


More Finished Than She Thinks

Dear More Finished Than She Thinks:

I assume that you, like most BAs, understand that requirements are rarely “finished” in the sense of being complete to the satisfaction of every stakeholder.

The most complete requirements ever written for a cell phone did not include the contingency factors inherent in a pair of boot-cut Calvin jeans worn two sizes too small and stuffed with an understructures oversize phone chassis.

Don’t even ask about rubber gasket temperature requirements for Space Shuttle boosters – they WERE included as requirements, but ignored by project management in spite of their completeness (“But Reagan is sending a teacher into space and giving a big speech – it’s a deadline!”). Deadline, indeed, but not a requirement.

SO, I assume that the words “finished” and “everything” means something different to your PM than they do to you. Let’s try a few definitions – if one of these fits you may realize what to do.

Does finished mean? :

  • I (the BA) can’t tell that anything is missing
  • She (the PM) can’t tell that anything is missing
  • We (the other Business Stakeholders) can’t tell that anything is missing
  • They (the Implementation SMES) can’t tell that anything is missing
  • It (the solution as implemented) can’t tell that anything is missing (everything” works)
  • Notice that none of these definitions involve anyone saying “I can see that X, Y, Z are missing” which would be more helpful.

Now for a definition that helps. Completeness is best defined at a GIVEN LEVEL OF DESCRIPTION. In the BA profession, we look to BABOK for the correct categories and levels of description. In this case, requirements have the following levels of description:

  • Business Requirements (High-level statements of key business needs, approaches and strategically justified capabilities that must be met regardless of stakeholder wants)
  • Requirements[Stated] (stakeholder wants and concerns not necessarily analyzed)
  • Solution Requirements (functional, work to be done)
  • Solution Requirements (non-functional, qualities of any solution to be implemented)
  • Transition Requirements (temporary needs and efforts, until “full” implementation)

“Our business has a need to deliver legal documents to its customers every day on less than one hour’s notice,” might be a COMPLETE business requirement. Make sure to comb your requirements and collect all the “high-level” actual business needs (as opposed to personal preferences, see below). You will discover some “low-level” requirements that imply high-level requirements, and vice versa. Separate them (analysis) into their own groups, rewrite them to fit their level and category. THEN IT BECOMES EASIER TO SEE WHAT IS MISSING AT THE HIGH-LEVEL. This is where MOST IT project mistakes get made and is the most important to get complete.

“I want a car so I can make those deliveries for the business” is COMPLETE in the sense of being a stakeholder requirement [stated, not analyzed]. Make sure that you comb your “requirements” and collect all the “not-really requirement” statements and put them into an “elicitation” document for further analysis. The “requirements” are not finished, because they are not analyzed, but COMPLETE in the sense of being everything the stakeholders said).

“Bicycle couriers average 12 miles an hour in city deliveries, vs. 7 miles an hour for cars. Feasibility ANALYSIS suggests outsourcing delivery to couriers (or we can buy the stakeholder a bicycle instead of a car).” This might be a COMPLETE solution requirement (functional) – DELIVER LEGAL DOCUMENTS. Collect all the actual work functions implied in all your requirements, and list them in one place. It becomes easier to see what is missing (e.g., PREPARE PACKAGE WITH CORRECT DELIVERY INFO, and CONFIRM TIMELY DELIVERY WITH CUSTOMER). To be complete, list all the IMPORTANT business processes, and let the less important arise as needed (e.g., we need to ASSIGN DELIVERY TO COURIER SERVICE as a critical business function, but we can decide to implement this assignment via text message as we negotiate with the courier service. Is the requirement complete, if this “text message” spec is unresolved? Not really (see the beginning), but it is LOW risk and focus belongs on other higher level issues (e.g., how to MEASURE delivery performance objectively, once assignments are made).

“Delivery in less than on hour” was already stated as a business requirement – it is (for this simple example) the COMPLETE solution non-functional requirement – a service level guarantee. Can you think of any functional requirements that would help guarantee that service level? Put those above – group like with like.

Finally, transition requirements. Who has to be informed, trained, won over? Do we have to convert data from the secretary’s Rolodex to a label print system for the courier packages? What is the implementation plan (oh project manager mine). The project plan (think about it) is largely “transition requirements”, and should lump upon the head of your PM as much as on you.

IN short, if you use BABOK categories, you avoid level mixing, confusion, and you gain the ability to see what else belongs at that level. If you do it right, you will perceive redundancies between levels. This is normal, and shows traceability and shows that requirements are related across levels (that is why it is so easy to mix them up and get confused about how complete they are). An example of a seemingly redundant requirement was “Delivery in less than an hour”. At the business level, it is a service strategy defined by a performance level. At the non-functional level, it drives measurement, verification and other functional requirements. By putting it in both places as appropriate, COHERENCE is achieved, which helps stakeholders in perceiving completeness.

ALWAYS START BY FILLING IN THE HIGH LEVELS TO MAXIMUM COMPLETENESS. IF there is no time to “finish” a lower level, you might not even start it. Don’t spec the detail steps of MANAGE USER PRIVILEGES just because you can – stick with high value high-level critical business processes such as VERIFY TIMELY DELIVERY, and try to “complete” the success scenarios. If you have time, go for the top 3 alternate scenarios. At each step, decide how much you can accomplish and put BABOK boundaries on the work so the completeness can show.

THEN when your manager says to “finish” the screen color requirement, you know which requirement and what is missing.

Je suis finis – et vous?

Please comment below – let me know what you DIDN’t get, so I can finish it 🙂

BA or Not BA

Traceability matrix Slavishly make this
Functional decomposition Dump on free thinking positions
Balanced scorecards Biased scarecrows
Verify requirements Vilify requirements
Active listening Passively missing meeting
Clarity, completeness, coherence, concision Confusion, carveouts, crazy, carrying on & on &…
Prioritization Riot promulgation
Enterprise architecture Architect renter prizes
Decision analysis Revision paralysis
Agile methodology Methodological fragility
Measured outcomes Declarations of victory
Brainstorms Stormdrains
You found the error You didn’t find the error

Thanks for reading, and be sure to use your comments (BA) not your fists (not BA), below 🙂

Even Business Analysts Need Love

Attention all stakeholders of the solar federation. My personal life has recently tuned me into pain in a way that makes me realize that the BA’s professional life offers great pain. “NO!”, you say, yet here is a list of hurts you may well have inflicted on a BA if you think about it carefully.

Don’t do these things:

Don’t kick the BA off the project just because they made a deliverable that looks like requirements to you even though you didn’t read it (sponsor, sponsor, sponsor). Your (anyone’s) deadline allows only the beginning of organizational learning. The loss of the BA guarantees the end of learning, never mind the teaching that must follow for change management success.

Don’t hire a BA if you know better than they do. You will annoy yourself while amusing the BA, which will only annoy you more.

Don’t give requirements as if they were dictation. If a BA takes your requirements EXACTLY as you give them and does not present an “analyzed” model showing what the requirements might REALLY be, it might even be that your BA does not like you.

Don’t dislike the BA. At worst they are only messengers, and at best they can get you results that you actually want.

Don’t withhold pay. Because may BA assignments are “temporary” (see above), many BAs are consultants/contractors/temporary. Making them wait long periods to be paid is not good for them, you OR them.

Don’t keep the BA in the dark. They can see how silly you look in the dark

Don’t yell at, or curse at the BA. Yeah, really. You know who you are, and so does everybody else on the project. Recriminations are not requirements. Not.

Don’t not read the requirements.

Don’t not read the email. Yes, it is OK for an email to have more than one sentence.

Don’t gush over the diagram just because it is nice. Be specific in your gushing, as in “I really like the fact that I can see ALL the redundancies across payment types” or “The pink really highlights just how risky a full cutover is, and how it pays to set up three teams.”

Don’t be impressed with nice looking diagrams unless the content is robust. The cuter the graphics, the less likely the analyst spent time on re-factoring process, the more likely the analyst spent time on re-factoring the format.

Don’t bring everyone to every meeting. The amount of work progress made in a meeting is inversely proportional to the square of the number of people. Eight people will accomplish 1/16 of the work that 2 might. Enforce the rule by accomplishing actual work at every meeting. This will help you keep meetings small.

Don’t accuse the BA of “blowing your scope”. It isn’t your scope, it belongs to the business. Besides, you got the scope wrong in the first place by rushing to solution, then broke everyone’s spirit by preventing any improvement once the team understood what the scope actually meant.

Don’t rush to solution. Plan the different approaches, from simple/cheap to complex/low chance of success. Use each simple approach to advance the solution by REALLY learning from it. REALLY.

Don’t have the BA walked out the door immediately, even when you must let them go. They don’t have access to sensitive systems functions (are they sysadmins or BAs?) and if what they know is dangerous to you walking them out is no way to make friends, and you are going to need friends (see 1st item above).

Don’t ignore maintenance of the highest level descriptions just because “everyone knows that”. If you are engaged in enterprise systems transformations, everyone is going to go from 5 people to 10 people to 40 people over a couple of years, and then to 20,000 overnight. Be ready for everyone – there will ALWAYS be new people, and a failure to model the highest levels of business requirements and process is the number one cause of failure – the big mistakes happen at the top levels of description.

Don’t insist that BAs produce meeting minutes – better they should produce models that represent business thoughts and decisions so stakeholders can see what they said. The alternative is to build based on the say as seen in the minutes. Then you will hear stakeholders say “I can’t say I see what this does for me.”

DO learn along with your BA, who is learning your needs and combining them with others that you don’t have time to learn. So many voices channeled through one, neutral, zero attitude model for all to reflect upon. Bliss, you think?

Don’t forget to tell me what you think, since you read this far, your opinion is already 1st percentile. Comments below 🙂

Don’t forget to leave your comments below.