Blog of a Boston-based IT Consultant

I have been struggling lately. It is a private battle, and I don’t think that it shows.

I am consulting part time with a team of Project Managers that is used to writing Use Cases that read like miniature novels, complete with detail including prose such as, “the User will click the red button in the lower left corner of the page that says ‘Click Me‘ and then they will be able to share content.”

I have no delusions of grandeur. Well, maybe I have a few small ones (I think I can cook fish pretty darn well). Still, I know that as far as this particular organization goes, I bring a new perspective upon Use Cases. The PMs that I am working with are not technical Project Managers (but they are very talented) and although they have had formal Use Case training, the lessons did not stick. The PMO did not enforce what they learned and did not work to doccument and uphold Use Case standards. The reason for this is too complicated and potentially boring to get into. I’d rather keep rocking your world with this spine-tingling account of my Adventures in Documentation.

People will tend to gravitate towards what is comfortable, and since the development team was used to receiving Use Cases with sketches inside of them, when I proposed the “Barely Good Enough” approach that they were taught, I was largely ignored. My proposal did not accommodate their expectations and so a small degree of panic and a larger degree of resistance set in. This is to be expected, and there are ways to deal with it.

One way to deal with it is to stick to your guns and start small, see the larger picture, stay the course and offer your opinion without presenting it as gospel. I can certainly think of more noble causes than Use Case Evangelism. However, for whatever reason, I truly believe that documentation is an astonishingly powerful tool and am proud that I am fairly skilled with it. I don’t know if this explains it, but the idea that you can - through effective documentation - take a maldefined, nebulous, ambigious idea and turn it into a reality that people can use and benefit from is really cool to me. The entire process of project Inception, through Scoping, Requirements Gathering, Execution, Design and Development, Testing, and then Implementation is held together by this thread of traceability.

I think it is a fantastic when you can apply discipline and keep this traceability clear, clean, and lucid. It can ensure that you arrive at your lofty goal. It can to connect you to your vision much like a fishing like connects you to dinner. This traceability is invisible unless you know what you are looking for, and it’s one of those things I just happen to get a kick out of. It requires a lot of fine detail and an expansive perspective upon the bigger picture.

So today, as we were had a conference all regarding Requirements Definition and were looking at the more detailed technical end of things, it became apparent that this SharePoint 2007 implementation will require the development team to retool many of the existing classic .asp files. Some data-driven Flash needs to be migrated and coded to operate within the new environment. In the case of these Flash files, this means that interfaces will have to change.

When this became obviated, the room of Project Managers was stunned into silence. I heard it. They were going to have to redo their Use Cases. There were at least a hundred Use Cases affected.

This simply should not have happened.

Use Cases are supposed to describe the functions that the System will accommodate and the actions that an Actor can take upon the System.

In Use Cases, an Actor “indicates via the UI” and does not “click the red button that says “Click Me” in the lower left corner.” At least, they are supposed to.

So I have been the renegade consultant, quite leery of explaining *again* the veracity of proper Use Cases for fear of lynching. (Not really. We all get along very well.) I tried. I really did. I stated the case gently, firmly, and in every non-offensive way that I could. That is what I was hired to do.

People listened, too. They even understood. However, when they went back to their desks and started documenting, old habits took over. Even when there are not time constraints as significant and scary as we are dealing with, people tend to do what they can do quickly, with the least amount of pain.

I am the first to admit that Use Cases can be especially tedious. I think part of the reason that they are tedious is because you are forced to document things that seem really obvious. (Or very complicated, of course.)

I also think that the assumptions that are made when things are deemed obvious are what leads to a lot of problems in software development. Assumptions make an ass of u and mption. Or something.

I was quite pleased that I did not have to redo any Use Cases and that a small victory for “Barely Good Enough” was won. I do find it odd in some ways that the argument for less “technical” detail would have to be argued when technical detail is what causes pain to folks who are not familiar with it. You would think people would welcome the chance to write less, but better, docs.

No, I do not think that naming page elements is especially “technical”. A lot of other folks do, however, and at first glance I understand.

But again, a lot of resistance comes from the corporate culture and like all things dynamic, corporate culture will change. I expect resistance will start to wane. I hope that I don’t come across as preachy or too self-assured, but it felt pretty good to have even that small moment of vindication.

As a consultant, you often find yourself working with people who are unfamiliar with your toolsets and methodologies. Sometimes you are all alone with your specialized, otherwise useless tools. It was great to have some of my speeches elucidated via real life.

Some of the documentation PMs and BAs produce look scary to those who are not familiar with them. This is part of what is happening right now as well. I asked a woman to look at some UML that I drew up today and said that she could not understand it.

I asked her to try. I asked her to just read it.

She could. She just didn’t know it until she tried. It was, in fact, pretty easy.

It was a decent day in some ways, and I like seeing people smile because of UML. I also like seeing people inspired to learn about Use Cases.

I am, in fact, odd.

- Josh Milane

MIT Technical, Boston

Project Management | RSS 2.0 | Comment it , or trackback this post.