Skip to main content

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!