Smoothly is in the eye of the beholder

[caption id="attachment_113" align="alignright" width="300"] Smoothly is in the eye of the beholder.[/caption]

Do you know that feeling of exasperation, or worse, dejection you feel when you fall over the line after a marathon heroic work effort? Having sheltered your client from all kinds of untold pitfalls, looked ahead, anticipated, mitigated, designed cleverly, implemented and delivered, all you get from that blissfully ignorant  recipient of your herculean deeds is "Oh, that's nice, what about the other four requests I sent last week?"

I'm learning that quite often, it's just as important to communicate plans, hurdles and be sure to highlight roadblocks and even technical issues your client's can't possibly understand. Sometimes, "things just running smoothly" isn't enough. Because sometime (often) "smoothly" is in the eye of the beholder.

In consulting (and software development) you do have to check your ego at the door. I get that. But sometimes credit is important. Not necessarily for your ego, but for the good of your project. Wouldn't it be terrible to lose a project because the customer doesn't know how well you're really doing for them.

"I told you so", months from now when you've been replaced, doesn't pay the bills.

When you're making great progress but no-one knows because solutions are clean, elegant and "look simple", all they can see is what isn't getting done.

If the work is laid out, prioiritised and everyone has buy in, and sees the impact of changing priorities, is seems they are happier to achieve A and B, and know when, how and why C, D, E & F aren't ready yet, than they would be to achieve A, B, C & D and still be waiting for E & F!

Communication! It's should be easier than doing, and will quite often help just as much.

Don't confuse a band-aid solution with a bad solution.

Sometimes people confuse a "band-aid solution" as a bad solution.

In any business, and in particular in software development processes break. Things go wrong, or stop working. The environment changes and what once worked, no longer works. Other times, people just break things.

A "band-aid solution" to such problems is one that isn't going to last forever. It might be perfectly sound, well thought out, even brilliant. It's going to hold, cover up the problem until it is properly healed.

That's half the value - coming up with an idea, or a solution to a problem that is sound, complete and clever. The second half is in the execution. The delivery - delivery you solution in a way that sticks. In a way that is complete, and that scales - for everyone.  Otherwise it's just a band aid.

If there's a problem with something at work, at your sporting club, at home, to fix it and have it stay fixed you need to get to the heart of it. But the fix needs to be implemented in such a way that no-one else needs to fix it next time - in fact, no-one else will ever even notice the problem.

Identify what's wrong, identify what's missing, design a solution that rectifies this, and implement it - but don't just patch the gap. Put enough infrastructure, or support around your solution that it lasts. Your solution becomes part of the fabric of the system you've solved, so it can never happen again.

This might mean going right back to basics - documenting your process, garnering support for a change to the process or the adoption of a new one, roll it out, monitor it, make it "business" as usual. Then, it's fixed, for everyone, until it needs changing, or someone else decides, your solution, is a problem. Then, they can do the same. Identify, what's wrong, design a solution....

In the meantime, what was broken, can be should be fixed with the help of a band aid.

We need to fix things, so they stay fixed. Band-aids can help.

Bug Reports aren't just for developers

I've read a lot of bug reports over the years, maybe that says something about my coding? Maybe I shouldn't admit that?

For a software developer, having someone tell you what is wrong with your pride and joy is often confronting.  It can be challenging to stay positive and mature about it. Check your ego at the door is some advice I once heard about designing, building and delivering a software solution.

Dealing with bug reports is however one of the day's chores. One you'd prefer not to have to deal with. You should of course welcome the opportunity to correct a mistake in your beloved system and make the world a better place, but the truth is, you really wish they just weren't there.

So once you've steeled yourself for the task of opening that next bug report and you've summoned up every ounce of reasonableness, empathy and altruism you possess, it is supremely frustrating to then have to spend more time, sometimes a lot more time, playing detective and deciphering bug reports which can often amount to nothing more than some observations of what coincidentally happened the last time they ran your program.  Maybe they're not quite sure exactly what steps they took, or weren't quite paying attention, or didn't realise they were supposed to be. This is the difference between a user providing an account of something that just happened on their computer to help desk or tech support. It's their job to investigate and solve, but a software tester in a development team reports a bug in order to get it fixed.

Testers, like programmers, are part of the development team, contributing to finding, analysing, identifying, documenting and eradicating problems. In small teams especially though, it's easy to overlook this important role and just rely on some people who are on hand and "know the system" well enough to "test it" for you.

For a developer, sifting through paragraphs of observations and screen shots that someone has "noticed" just to get to the essence of a problem that you wish wasn't there in the first place, takes all your resolve. You really have to want your product to be better. In these moments, the risk to the software product, the team and the overall betterment of the world in general, of losing the opportunity to fix a genuine issue is high. Making me work incredibly hard to understand what you are saying, when I'm already looking for any reason I can find to reject your point in the first place, is not playing the team game.

What is even more frustrating than this however, is to have a previously fixed bug returned to you, with some rider attached, like a bill in the US parliament, just because whoever was testing it happened to stumble across something else while running through a test for this item.

My latest message to the team, and it is working, is...

Bug reports aren't just for developers... they're for all of us. They benefit of the whole team and the product.

Someone has to test this again , someone may need to use this resource - the bug report, this small artifact, to glean some information from it some time in the future. It is also the goal of the whole team to identify these issues and communicate them efficiently, get them fixed, and move on with confidence in the product, for everyone. It needs to be concise and clear for many reasons over and above just making some precious developer's life easy.

So my tips for a good bug report:

• A brief "punchy" title that states the problem in it's most serious case, without exaggerating, lying or over stating the issue.


• A description that explains the title, and gives a little context. This is not always necessary - only do this when it adds value (which is when the "punchy" title needs some clarifying).


• Reproduction procedures that describe how to reproduce the bug in it's most simple form. Steps that once followed and no longer result in the described issue, mean it is fixed across the board. This is the key. Show me the most succinct way to reproduce the problem you've found. Don't include 8 other steps, unless the issue only occurs if you do each of them, in a specific order. This is because, to fix a problem, you need to get to the heart of things, and fix the underlying fundamental problem.


• Desired outcome - this one is not mandatory either, because quite often it will simply be "that the error doesn't happen", but sometime developers will need to know, your were expecting "X" or you require that "Y" doesn't happen there.

That's it. That's what I need to know, to fix the problem. Someone on the team is going to do this work. The more the load can be spread, the quicker things will get done.

Oh, and by the way, don't underrate how hard this is. Succinctly describing what you've discovered, and doing all the extra analysis to eliminate superfluous information, discover contributing factors and isolate a problem, is hard - as hard as writing the program, but remember, someone on the team is going to do it before the bug is fixed. It cannot "not" be done - the more that can be done early in the process, the better.

The good news is, the bug reports are improving. As a result, I think the product will too.