I first told people about why it broke at 6am five years ago.

The background to this is not complex. It relies on verbal and written communication.

A practical example. Someone says 'excuse me please', as they get off a tube in the morning rush hour.

They are not just being polite, they are showing their intention. People can move out of the way, get off…… The people wearing headphones are not part of the equation.

You may simply push through the crowds, and get off. But you are not really helping yourself, or anyone else.

Back to the subject at hand. Why did Marmaduke break at 6am? The thing which broke was subtle, intermittent, and only happened occasionally.

The clue is not the what, but more the how.

Marmeduke was created by a very skillful software engineer, and seemed to meet expectations. There was one flaw. One component was not implemented correctly. It worked, but should have been designed differently.

Now this is not about blaming people. That would be easy. Marmeduke passed all the unit, integration, and other tests. Boxes ticked.

The problems started when Marmeduke needed to be changed. There was nothing which told the story of how Marmeduke “had” been implemented. The technology decisions, the learning, the subtleties, including the discussions, and the IRC chat transcript.

As soon as Marmaduke broke at 6am, the DevOps team started investigation, root cause analysis, with a log of what was found.

What a shame the developer who implemented Marmaduke hadn’t done the same. I’m talking about a record of design decisions, tutorials followed to learn the subject matter, decisions made, and conversations.

Text, mind map…..how this is represented is up to you.

The gist is that you are helping the team understand how, and why Marmaduke works, including tenuous assumptions.

Tenuous is fine. Sometimes that’s what is available at the time.  But why wouldn’t you record that?

An architect produces design drawings for a house. Why should software development be any different?

Telling people about it

There is no point in keeping transcript Marmaduke in a dusty filing cabinet. You need to tell people about it.

Brown bags, learning lunches, a blog, a wiki. Make sure that what you have to say (present) is concise. But don’t be afraid to state the tenuousness of the decisions you made, with justification.

Answer questions, make notes of suggestions, feed these back into Marmaduke, even if Marmaduke is live. Make a note of the 3am improvement (keep a notepad by the bed). But make it clear it’s just that, an improvement.

None of this is complex. It’s called communication.

Don’t just say “read the docs”, or look in the code.

If you show the team how you joined the dots, building Marmeduke, the devOps support, and refactor to fix Marmeduke will be that much easier.

This isn’t agile. It’s common sense, and common practice.

Why is it not second nature in software development? I don’t believe that all coders are bad communicators.

This is one simple thing you can do to improve what you deliver, and build your brand.

Back to the guy with the headphones on. Do you want to be that person? If the answer is yes, you are either a contractor, taking advantage of your client, or you are the stereotypical geek in the corner.

I am certain the geek in the corner can communicate, join the dots, and tell people about what they have learnt, decisions made, and tenuous decisions.

The contractor with the headphones on. That is a topic for another time.