We have been trying to get our client to realize that the solution to people not reading huge requirements documents all the way from development to QA to support is not more documentation, but more communication.

We are all for documentation, but only the kind that people will actually read.

Last night, as I sat with my grandsons reviewing their five and seven year old accomplishments, I was drawn again to memories of my own childhood experiences. Joey, my seven year old, proudly displayed his ability to write in handwriting, which had mostly been learned through self teaching, some of his capital letters. This, despite the fact that his mother was repeatedly requesting that they say goodnight and get ready for bed. “Let me show you a capital T, Gramma”, he said, laboriously outlining his project. “Oops!” I remarked, “You shouldn’t have crossed the T, honey, that makes it an F.” There was a stricken look on his face, and with an “Oh no!” he left the room. He returned shortly with his specially wrapped gift for his parents which had a large beautifully made capital F in “Fo Mom & Pop.” I whispered to get an eraser and we would fix it and he went and desperately began searching the drawer where such things were kept. Mom, by this time, and not knowing what was going in, demanded that bed time was now! And she forcefully directed him toward the stairs. The enormity, to him, of his predicament, started a totally frustrated cry, but he went upstairs. When she returned I briefly told her what was happening and went to call the sobbing child for just one minute. I explained to him that if he added a small “r” to the “Fo” it would change the word. With brimming eyes, and a moment’s thought, he realized it would say “For” which was perfectly acceptable. Tears stopped, the correction was made, and a true weight had been lifted in his young mind.

The enormity of unresolved calamities of my own childhood, though they are small by adult standards, still come back to haunt me. Not that adults were uncaring, but there was an opinion that because children were small, their feelings were relative to their size. Not so! The adult is wrapped in a small confining package, straining to find answers to enormous complexities in the child’s body.

I miss you Grandma.

I tend to use a lesson learned long ago to escalate problems I’m having with people.

First, talking to the person is often the earliest and easiest way to give someone feedback. Often people will not know something is wrong and are more than willing to fix it.

Second, if the person doesn’t respond, let them know you will take your feedback to their boss if needed. Give them a timeframe to improve and tell them what you will do if they don’t.

Third, evaluate how the person is doing and possibly even get a second opinion.

Finally, putting honest feedback into a review will help teams evaluate the person’s strengths and weaknesses for the future. Even bad feedback with a good outcome can help someone’s review for the future. Who doesn’t like to see someone improve?

When you sugarcoat a review, you hurt the person by not letting them improve and future teams they will work with by not letting them see where they need to cover or help someone.

Firefox Extension

A quick and easy solution is to use a Firefox extension that can automatically refresh any page called ReloadEvery. This is probably the least amount of work and works just fine.

HTML IFrame

I’ve also created a small bit of HTML that uses Javascript to refresh an IFrame that takes up the whole page. Just change the google URL to whatever page you need to point to and the amount of seconds you want it to refresh (set to 5 right now). It works in all of the browsers I could find.

Download Radiator

I’ve provided a download of the xml file here.

You’ll need to edit the file to point to the Mingle project you want to use the search tool with and then you need to install it into your searchplugins directory for Firefox, which for Windows is probably something like

C:\Program Files\Mozilla Firefox\searchplugins

and for Mac is something like

/Applications/Firefox.app/Contents/MacOS/searchplugins/

Drop the xml file in the folder and restart Firefox and you’ll have your new Mingle search up and running. It should look like this

Note: I’m working on getting this to work as described in this mozilla dev article for Mingle. It shouldn’t be too hard since we can modify views in Mingle. I’ll blog about it if people are interested.

Click the “All Controls” radio button at the bottom of the Keyboard & Mouse pane in System Preferences to right this wrong.

Bliss.

[via]

My problem comes when the people building software turn from distrusting their user’s input to having a level of disdain for the users themselves. It starts innocently enough with the engineering principles I described above, but can sometimes turn into small things like, “Our users won’t understand that,” and starts to slip into things like, “Our users are dumb, so we won’t do that.” If you’ve started to hate your users, you’ve gone too far. If something is too complex for your users to understand, it’s your job as the developer/engineer/analyst/etc. to make it so that they can understand it. If you think of your users like idiots, your system will reflect that and they will notice.

If your job is to design software for people to use (which, is pretty much all software), make sure you work with the user, instead of against their best interests.

This just confirms my suspicion that developers fully don’t read the stories that I write for them, even though they are highly focused and relevant to what they are looking for. Instead of reading, they skim and look at the screenshots I provide.

What can we take away from this? Treat stories as a conversation point, rather than a full design spec. If your devs have to read thousands of words in your stories, they are too big. Talk to your team and make sure people understand what you are trying to do.

At 130 words above, most people have read only 26 words in this article, meaning they’ve barely read the first paragraph. Scary.

Master Level Story

The high level stories written at the beginning of a project and turned into a master story list can either have a long shelf life or a short one. If the requirements are not beginning to be broken down and worked on within a week or two, they get stale. Longer than a few weeks, into a few months or more, they should probably be thrown out and at the very least reevaluated. Why? Because your business may have changed in that time. It may not make sense to build those features that made sense a month or two ago.

Release Level Story

Release level stories are good for planning and immediately getting started on detailed analysis and development. They have a short shelf life based on their master level story freshness, plus any ongoing work in an application. For instance, if some implementation was decided on in a release level story and some technology change has made a card obsolete because it is building the wrong thing or makes the wrong assumptions, it’s useless.

Iteration Level Story

An iteration level story only has a shelf life of a few days after it’s been analyzed and not developed. More than a week or so and things can change so drastically in a project that they are not accurate anymore.

Shelf-Life After Development

After development, stories have a much longer shelf life. They can be referenced through various parts in the development lifecycle with the exception of stories that have been overwritten by new ones and those should be tracked as they occur.

Domain documents like systems architecture design, major domain concepts in your app, etc. are useful even longer.

Considerations

Keep in mind that all of these levels of stories interact. Master > Release > Iteration. They flow in that order and if the master level stories are old and no longer good, they need to be reevaluated. Otherwise, spending time to break them down will be a waste of time and even worse, implementing them can cost real money in the marketplace.

Constant prioritizing and re-evaluation will keep stories fresh for use by the development team. Don’t expect to be able to pull bad apples from storage and make some great apple pie.

@namespace url(http://www.w3.org/1999/xhtml);
@-moz-document domain("my.mingle.installation.com") {

.project {
   float:left;
   height:100px;
   width:300px;
}
.action-bar { clear:both; }
.round-corner-wrapper { height:91px; }
}

Your project list will then look like this:

One thing to note is that it doesn’t currently handle long project descriptions too well right now. I’ll try to get that fixed and I welcome any fixes to the above CSS changes to make it better.