free html hit counter
Posted on: Tuesday, October 31, 2006 by Rajiv Popat

Analyze This!

When I first came across Microsoft development Platforms, in the QuickBasic days, I was hooked. Because the tools allowed me to produce results. Single handedly. In a short span of time. I could write proto-types and see things happening.

Even today, my reasons for sticking to Microsoft tools and technologies (and trying to bring developers from the "other side" over to Microsoft tools and technologies :)) remains the same - Productivity.

A couple of days-to-a-week and I can cook up POCs that convey the fundamental vision of a huge module to everyone involved. We can have brain-storming sessions, take notes. They don't like what they see? I can move big chunks around and give them something they want in a matter of hours!

Whiteboard meetings / Conference calls > light weight documentation > quick releases (every month or so) > Feedback (cycle). That's how most Microsoft Developers (me included) love working.

A few days ago, an ex-army officer who is now a HR person in a software development firm, wanted some help on how to do Business Analysis asked for my help. He wanted me to review the detailed Use-Case Documents he had written for an internal project that he was analyzing for his company.

This was his First Attempt at Business Analysis and he had already prepared:

  1. Lengthy Use-Case documents.
  2. Visio Wire-frames that were as detailed as capturing widget level validation!
  3. Detailed Visio Flow Diagrams.

He was a smart individual taking his first steps towards Business Analysis and has asked for genuine advice. It was time to take a pause and have a little bit of discussion. My sole objective was to convince him about a few things:

  1. Writing complicated documents and making complicated diagrams, has nothing to do with "Business Analysis".
  2. Business Analysis is no different then rest of Software Development, where Occam's Razor and Kiss are the only two principals that work. Not Waterfall.
  3. Knowing what you are doing is more important than making really complicated diagrams on what you are doing.
  4. Use simple tools. (Unless of-course, in very rare situations, when you have to use complicated ones!)
  5. The best Analysis and Design tools ever are White boards, PostIt Notes and the Human Brain! :)

Steeve Yegge is his long Rant about agile says:

"Most great software developers around the world don't use Agile. They just work hard, they stay lightweight, and they ship great stuff. Most developers still have no idea what Agile even is. Think of that!"

It's interesting to know that even something as light and flexible as Agile doesn't sound light enough to Steeve. I wonder what he would have to say about Waterfall, RUP and writing a detailed 12 page Login Use-Case document :) Anyways, I digress. On a serious note however, isn't the same statement valid, in practically anything you do in life, including Business Analysis?

Being lightweight in a Software Development firm like wearing casuals at work. In a more mature organization / teams / work-cultures they'll understand. In lesser mature ones - they'll look at you with knitted eye-brows when you walk into office with that black T-shirt and Blue jeans. But that's OK. As long as you keep shipping quality builds on time.

I've always believed in putting some thought into what you're building before you start building it. But, I was never quite a Use-Case document guy myself. So what do I feel about some other techniques of documenting requirements:

  1. White board diagrams? - Definitely!
  2. User stories? - Sure, as long as they don't go more than a couple of paragraph each.
  3. HTML Mockups? - Sure! (As long as someone else makes them based on white board diagrams :)).

Scott W. Ambler makes an interesting point:

"The longer your project team goes without the concrete feedback of working software, the greater the danger that you're modeling things that don't reflect what your stakeholders truly need"

I've heard of projects, in so called Huge Indian Software Consultancy firms, where there are specialized teams for synchronizing Use-Cases with code, Specialized guys for just filing bugs (These are guys who file bugs NOT find them!) and specialized guys for Formatting these Use-Case documents and versioning them. I've heard stories of projects failing in these environments from friends and I am told that when they do fail it's a very ugly process basically focused towards: "We have the documentation and the proof! Let's track down the culprit!"

A friend who works in one such Large Indian Software Development Firm describes their check-in process:

"We're not allowed to check-in code or fire builds. We check-in to a different source control and email the Build Manager. Who reviews our changes and commits them to a QA source control system. A Business Analyst runs those changes and verifies that they confirm to his Use-Cases. Then the tester runs Test-Cases, which are built based on Use-Case documents and does manual testing after which the Build Manager checks our changes into the Primary Source Control System which only he has access to. All changes including caption changes of labels go through this process. We build based on Requirements that have been analyzed carefully!"

I had to quote him on this one. It's been weeks since that discussion with him and even though the words aren't exact, but the idea is precisely that.

Then there are companies where people have one meeting and start writing code. A person I was interviewing explains their Process and how they Analyze Requirements and Develop software:

"Some of us use Visual Studio 2003 while some have moved to Visual Studio 2005. We are all free to choose our own IDE, frameworks and do our thing with code. We have a couple of meetings with the clients... and then we code."

Wow! Both aspects sound equally scary to me. The first one, more often than not, leading to Analysis Paralysis followed by a search-for-the-guilty phase every time something unexpected happens and the second one... let's not even talk about that. 

Walking on the middle path is difficult. You need focus, balance and a team that takes work seriously. At the end of the day, if you really think about it:

  1. Shipping regular weekly builds and having Continuous Integration and letting everyone "see the status" is difficult - Sending weekly status reports in word files is easy.
  2. Shipping a fully functional POC is difficult - Making Use-Case diagrams and Flowcharts (which, most of the time, don't cover all flows) is easy.
  3. Having a white board brainstorming session with the stake holders and managing scope are difficult - Writing a 26 page Use-Case document that confuses your client is easy.

Didn't we all come here because we wanted simplify and get the difficult stuff right? Analyze this! And btw, please don't write a detailed lengthy Use-Case document on this Post! :)

Thursday, November 2, 2006 1:43:50 AM UTC
Soooo Rajiv what do YOU think is the best way to go about it. I got a bit "tricked" {nice job of doing that, usually its me confusing others} in the end because well hmmmm it seemed like you took a U turn LOL
Thursday, November 2, 2006 2:49:12 PM UTC
I think Einstein got it right: Everything should be made as simple as possible, but no simpler – that comes pretty close to what I think is the right approach.

If you can do with 10 line Login user-story don’t write a 13 Page Login Use case document; if you can do with 1 white board diagram don’t write a 10 line user story. Keep going lighter till you can go no further. Soon it becomes a way of life and you know how light you can afford to get (of-course, this varies from project to project).

Login Use-case example found in a college project: User enters correct username but incorrect password, system displays message ER1001. User enters incorrect username but correct password… user enters correct username in incorrect case and correct password… user enters… well, 13 pages of… crap and a glossary of error messages that could have been summed up in… say, 10 lines, max?

And by the time I was done reading it I am thinking – “wow. This login stuff is pretty complicated”. And then I am thinking… Is this what we’re teaching our future analysts instead of teaching them how to conduct requirement ssessions on white boards and scope management? This guy is going to be responsible for a couple of really smart developers killing themselves. :)

I’ve done more than one small-medium sized projects without user-cases. In one of them, done a year ago, There were 3-5 odd pages dedicated to user-stories for roughly around 50+ screens that one of the project had and it worked out pretty well. Communication was pretty good, the team was serious and we were constantly “talking” with the client and showing them the Application every 15 days or so and had some basic HTML mockups for the complex parts, before we started them.

I share these experiences with some of my friends in so called really “process oriented” firms and they go - “What!!!? No Use-Cases!!!? What do you mean constantly showing them the application!!? What do you mean HTML mockups for only the complex parts!!?” – It’s interesting to see the reaction. :)

Everything should be made as simple as possible, but no simpler – that’s my stand.
Friday, November 3, 2006 3:59:57 AM UTC
I agree with that point - simplicity but here something to ponder about - what happens when you move to another project and someone needs to figure out whats going on? He/She cant call you, and well by that time the white board stuff is gone, and so are the requirements gathered through ears the principle in my mind is how do you get these damn use cases {dont tell anyone but i dont read them too :), i just code on the first sentence i read and then fix a small bug later}, to work without having to go through crap again and again ...

so here is my deal, i go in first, do the sketch up and basic skeleton, so that someone less doesnt have to break their head figuring out what the requirement is, then i explain what i did to someone else, [a better developer] and he also has the uses cases to support him/her as well as the requirements . then he/she can put in the little details ..i hate little details and bug fixing let me figure out the crap and sort it out for you, you figure out how to clean it ...could be a bad ploy but hey my personality doesnt suit otherwise
Friday, November 3, 2006 7:57:42 PM UTC
Yes, agreed. Like I said - “as simple as possible, but no simpler” - as a developer or business analyst (or anyone who works on a project) - it’s the person's personal responsibility to ensure that his knowledge on the project doesn’t get lost when he moves to a different project.

So the moment I feel there’s a piece of knowledge that might just get lost or might disappear with time, I open up a Wiki, document or anything (depends on project and methodology you’re using) and spread it around.

But I’m not sure what a Use-case document provides, which is more than a paragraph long User-story (since most developers, me included, don't read either anyways :)).

White board diagrams can stay forever, if you use digital cameras and paste the pictures into word files and then spread them around (using Wikis, Sharepoint, TFS or whatever it is that is being used in the project).

This sounded a little absurd (most good ideas sound absurd at first) to me when I first saw it in action in a product design demo I attended - but I've seen more than one good company take this approach and it seemed to be working quite well for a couple of them! Or, maybe have a guy from the documentation team just quickly copy one 1 white board diagram and put it into the document or spec. That way you get options of digitally editing them.

(On a side note: Making word documents out of white board diagrams was one of my first assignments when I started my development career. I hated it then, but it helped a lot, because I was reading interesting designs and trying to understand them when I was asked to copy those off the board into word documents – I got to attend some interesting requirement sessions early on in my career and of course it taught me Microsoft Word – a rare skill-set where even a lot of good developers suck! :))

Intranet Project Wikis and Discussion boards are a good way to capture and retain knowledge without writing lengthy documentation.

Your question - "What happens when you move to another project and someone needs to figure out what’s going on?"

You got me here! Just kidding. :) No, Seriously… He calls you! That is what usually happens – even when you have Use-cases. He walks up to your cubical and talks. That's what I see most developers doing even in projects where a couple of months have gone in writing tons of documents.

I did a project where we wrote a small device driver for a firm. We had all Use-Cases and did formal transition. Then, I kept getting question in emails from their development team for a month after I moved out of that project, and kept answering them till they eventually became comfortable with the code, what the code was supposed to be doing, what it was doing… and stopped emailing. My guess is that either the Use-Cases had gone out of sync, or no one was reading them anyways. Or maybe (and I am just speculating here) they were just not telling them what they wanted to know!!

Anyways, I personally feel giving pictures of white board diagrams and some basic User-stories tells a new team member pretty much everything a formal Use-Case document is going to tell him. And then if he doesn’t understand something – let him communicate with the rest of the team! Nothing can replace a good discussion between two team members. :)
Home page

Comment (HTML not allowed)  

[Captcha]Enter the code shown (prevents robots):

Live Comment Preview