Mark Needham

Thoughts on Software Development

Archive for the ‘Communication’ Category

Product Documentation: The receiver decides if it’s successful

without comments

One of the things I remember being taught while growing up is that in an interaction where somebody is something to someone else it’s their responsibility to do so in a way that the receiver can understand.

Even if you think you’ve done a good job of explaining something, the receiver of the communication decides whether or not that’s the case.

I’d always assumed that this advice made most sense in the context of a one to one conversation but recently I’ve realised that it also makes sense when thinking about product documentation.

Most products on the market have some sort of documentation available which is a good first step but I’ve still seen a couple of ways that users of the product struggle:

It’s too complicated

Frequently documentation is written by an expert of the product so the language they use is very technical and difficult for a novice to understand.

It’s often worth running documentation past a non expert to get a sanity check but a tell tale sign that documentation may be too complicated is when you get a lot of questions about things that you believe it covers.

At this point we can often work out what has led to user confusion and then make the appropriate changes.

People can’t find it

Sometimes there’s no problem with the documentation but people can’t find it.

This might be because it’s poorly titled or doesn’t use the same language that users use when they are trying to solve a particular problem.

There’s a tendency to believe that users should learn the language of the domain and while that’s true to an extent, if we can work out what language they use it can reduce friction and lead to a better experience.

The other problem users encounter is where they find the documentation index but are then overwhelmed with information to the point where they’re not sure what they should be clicking on.

This can be solved by focusing documentation on the simple case but having links through to more advanced topics for people who are interested.

Further reading

Tom Preston Werner wrote a post a few years ago around this topic titled ‘Readme Driven Development‘ which is worth a read.

Joe Walnes uses a similar approach on his projects – Smoothie Charts and WebConnect are a couple of examples that I’ve come across.

Written by Mark Needham

July 28th, 2013 at 4:18 pm

Posted in Communication

Tagged with

Presentations; Tell a story

without comments

A few years ago before an F# talk that I gave at the .NET user group in Sydney my colleague Erik Doernenburg gave me some advice about how I should structure the talk.


He suggested that in a lot of talks he’d seen the presenter rattle off a bunch of information about a topic but hadn’t provided any insight into their own experience with the topic.

If two people give a talk on the same topic they therefore end up being fairly similar talks even though each person may have a totally different perspective.

Erik suggested that people would find it much more interesting if I told a story about what I’d learnt about my topic (in this case F#).

I’ve been trying to follow that advice in other talks I’ve given since then and have noticed that there seem to be two main things that you need to get right for this approach to work well.

The Hook

Every story has a beginning but we need to find a way to take the audience from where they currently are to the beginning of the story and the amount of work that we need to get there can vary.

If it’s an audience that know the topic very well and are of a similar background to us then a quick explanation will do but we need to judge what our audience will be before working out how much context needs to be provided.

Most of the time I think people don’t get enough context and the talk becomes quite difficult to follow but I did give a presentation a couple of years ago where I ended up giving unnecessary context and watched people’s eyes glaze over!

In stand up comedy the key to a good joke is that you give just enough context so that the punch line of the joke makes sense. If you give a lot of context then there’s an assumption that the punch line is going to be stunning.

When writing jokes you therefore spend a lot of time refining the context until it’s just right. I think we should apply the same thinking in normal talks.

The flow

After we’ve got our hook sorted out and brought the audience to the beginning of our story the next thing to focus on is writing a coherent story which moves along at an appropriate pace.

The main thing to focus on here is to tell a story which is appropriate for the audience.

For example I recently gave two talks on a neo4j graph I’ve been working on with ThoughtWorks data – one to a ThoughtWorks audience and one to the neo4j user group.

In the first talk my story was an inward looking reflection on a bunch of data about ourselves and the tools I’d used to do that played a backseat role.

In the second talk I focused on the way that I’d iterated the model to answer questions that I had about the data over time.

In both cases I was able to identify a skeleton to hang the details of the story onto.

After we have a rough outline of an interesting story we need to fill in the details and make sure that the story actually makes sense and will be interesting to tell.

Sometimes this means switching the order that things would normally come in. I think this is ok – our goal isn’t to tell the exact chronological order in which we learnt things but to explain them in a way that’s easy to understand.

For example in my neo4j talk the order that I presented the questions I asked about the data wasn’t exactly the same as in real life. The points I wanted to make about modelling your data fitted better with a revised order so that’s what I did!

My way of preparing the story I want to tell is to sketch out some slides and then imagine presenting it to see if it makes sense – I often end up reworking it over a period of weeks until I’m happy.

It’s also useful to run through the story with someone else before hand to see if it makes any sense.

When not to tell a story

As with almost everything one idea isn’t applicable everywhere and there are other ways to present a topic other than giving your own perspective on it.

If you’re the expert on a particular topic and you’re presenting some new information about a language/tool then you don’t necessarily need to tell a story.

Having said that, a lot of good presentations I’ve watched tend to first describe the problem they’re trying to solve followed by their solution, which is effectively telling a story!

Another presentation technique is the ’10 things I learnt about…’ approach which makes sense if there doesn’t seem to be a coherent story line to weave.

Overall though I think the story telling approach is my preferred one and it pretty much mirrors what people do in normal conversations so we may as well take that familiarity with us when doing a presentation!

Written by Mark Needham

August 14th, 2012 at 10:16 pm

Posted in Communication

Tagged with

Dr Nic’s ‘How to stop killing people with your public speeches’

without comments

I recently came across a really cool blog post by Dr Nic titled ‘How to stop killing people with your public speeches‘ where he talks about the importance of practicing our presentations so that they actually make an impact on our audience.

Towards the end of the post he suggests joining Toastmasters as a useful first step for getting used to speaking to a group of people and as an added bonus you get feedback after each speech you give.

When I finished university in 2005 the one thing that I feared above all else was speaking in front of a group of people.

At the time I was an avid reader of Steve Pavlina’s blog and in one of his posts he recommended Toastmasters as a way of overcoming the fear.

I attended Toastmasters sessions every fortnight for about 18 months in 2006/2007, getting through 7 of the 10 speeches, before I decided to go off and learn open mic standup comedy, but that’s another story.

It’s a really safe environment to practice in because it doesn’t matter if you make mistakes and the other people are there to help you improve.

Apart from getting comfortable speaking to a group, the main thing I learnt from Toastmasters is that it’s much more fun doing a speech if you can see that the audience is engaged.

In order for that to happen that meant that I needed to write a speech which I found fun to deliver, an approach which can be applied to any presentation that we give.

In my case this means that there has to be some sort of humour in the talk but I imagine this may be different for other people.

A couple of years ago while I was preparing for a presentation I was going to give to the Sydney ALT .NET user group, Erik Doernenburg suggested to me that the talk would be more interesting if I put a personal spin on it and told it as a story.

I found that it was actually much more interesting to prepare the talk once I took this approach and it was easier to present since I was framing the talk as being about my experience rather than (implicitly) claiming to be an expert of some sort.

When I started at Toastmasters I used to write out my whole talk word for word but now I tend to have a rough outline in my head which leaves some room to ad lib depending on how it’s going.

I now feel really comfortable in front of a group of people so I’d certainly second Dr Nic in recommending Toastmasters as an excellent way of overcoming any fears of public speaking and honing the skill.

Useful resources

When I was a trainer at ThoughtWorks University presentations Sumeet recommended the following books which I think are worth reading:

Written by Mark Needham

November 16th, 2011 at 10:56 pm

Posted in Communication

Tagged with

The ladder of inference

with one comment

In Discussing the Undiscussable William Noonan describes the ladder of inference, a tool which can be used to help us achieve double loop learning with respect to our interactions with other people.

Ladder of Inference helps people identify what information or facts are used as the basis for their reasoning process.

It also helps people understand how they interpret that information and how they apply their interpretation to the issue or problem at hand.

Essentially, the Ladder of Inference is a metaphorical tool designed to help people understand and describe their use of inductive reasoning. Given what we see, what conclusions do we draw?

Ladder of inference

The book mainly describes the ways that we end up climbing the inference ladder ourselves but I’ve been thinking recently that it’s quite interesting to know that in all likelihood that’s how other people are thinking about the things that we do.

One of the main examples of people climbing the ladder of inference in an ‘agile’ context is when somebody comes late to the standup in the morning.

The other members of the team often jump up the ladder and come to the conclusion that the late person is lazy/doesn’t care about the project or their time and is generally a bad person, all before finding out why they were late!

The ladder climbing gets even worse if the person is a serial offender and even though it’s unfair to that person, it’s unlikely that you’re going to be able to get all the other people in the team to change their way of thinking.

It therefore makes sense to be aware that people may be making these inferences about our behaviour and perhaps adjust the way we act accordingly.

Written by Mark Needham

April 24th, 2011 at 2:11 pm

Use of language: Intuitive

without comments

Sumeet and I were recently discussing the difference between the use of Google Groups for internal communication compared to the Jive platform which we’re now moving to and I suggested that I found the former more intuitive to use.

Sumeet suggested that the word ‘intuitive’ is quite overloaded and later pointed me to an article on the Moodle website which advocates the same thing:

Intuitive is a word you should avoid in discussions of usability as its meaning is often confused.

It is generally accepted that a large part of usability is based on familiarity and experience.

Using ‘intuitive’ as a short-hand for something that is familiar often gives the impression that if something is ‘intuitive’ then it is so regardless of prior learning or experience and therefore equally true for everyone.

While the article is technically correct, from my experience it’s very difficult to get people to change the language that they use and to tell them to not use certain words is likely to provoke a defensive reaction.

I’ve found it more useful to look beneath the language used to work out exactly what is meant by the word since that’s what you’re really interested in.

In my case the use of the word ‘intuitive’ means that the way Google Groups works is exactly the same as other mailing lists that I’ve used previously.

Therefore when we moved to using Google Groups internally about 15 months ago it was really easy for me to understand how to use it.

The steps are pretty much:

  • Search for mailing list I’m interested in
  • Subscribe to mailing list
  • Messages on that mailing list come to my inbox
  • Job done!

With Jive the ‘algorithm’ has to be a bit different because you’re initially met with a new feed which contains absolutely everything that people have posted.

It’s conceptually the same as being met with the twitter stream for every single person using twitter.

The only difference I can really see between twitter and Jive is that twitter doesn’t default to having every single item on your stream, you have to build it up yourself.

That was pretty similar to the metaphor being used by the Facebook news feed which I was already familiar with and could therefore get the hang of very quickly.

On the other hand I’ve found it more difficult to work out how to reduce the noise on Jive so that it would only contain information I’m interested in.

It would probably be possible to find some documentation that would explain what I need to do but I like it better when I can work out how to use something myself without external help.

Maybe it’ll just take me a bit longer to work out how to use Jive and then it’ll be as intuitive to me as Google Groups and twitter are.

For further reading, Jared Spool has an interesting article where he goes into much more detail than I have about what makes a design seem to be intuitive.

Written by Mark Needham

March 13th, 2011 at 1:39 pm

Posted in Communication

Tagged with

Pecha Kucha: My first attempt

with one comment

The first time I came across the Pecha Kucha style of presenting was at the XP 2010 conference during the Agile Suitcase session where Pat Kua and some others talked about the practices, principles and values they most favoured.

I’ve never done one before but as part of the preparation work for ThoughtWorks University each of the trainers had to prepare one which we then presented to each other yesterday.

Despite the format being different than a normal presentation I still think the general idea of presenting any information applies – if you can tell it as a story then you have a much greater chance of keeping people’s attention.

This was advice that I first got from Erik Doernenburg almost 2 years ago when I was preparing to give an F# presentation.

I guess everyone has their theories and guidelines of what makes a good presentation but for me the underlying idea is that it has to be fun for me to present.

If it isn’t then it’s going to be really difficult for it to be fun to listen to.

These were some of the things I learnt from the whole process:


  • I generally don’t like rehearsing exactly what I’m going to say because I think it makes the presentation a bit less fresh when you actually do it. In this case however you need to have a reasonably good idea of how much you can talk in 20 seconds so it makes more sense.
  • A side effect of doing this was that I realised how much I had originally planned to cram into some of the slides and was therefore able to split some of the narrative out onto another slide.
  • Most of the ideas around slide design came from the Presentation Zen presentation that Sumeet gave us earlier in the week. I haven’t read the book but from what I’ve heard it seems to give some pretty good ideas for making slides engaging.


  • I tend to improvise quite a bit when presenting so I often throw things in that I think of at the time. The problem with doing that in a Pecha Kucha is that it can ruin the timings that you’ve practiced beforehand!
  • I looked back at the slides way too much which I only realised from watching the video that Sumeet had recorded.

    I think it’s a bit of an instinct because in a lot of presentations I’ve done you want to point out something which is on the slide.

    In this style of presentation it was unnecessary.

  • People interpret images differently – even with an audience of just 7 or 8 it was noticeable across the different presentations that some people understood or could relate to the images used by the presenter and some couldn’t! I’m not sure exactly how you get around that problem.

Overall I think this is a really cool presentation style and one that I think should be used more often.

Someone actually suggested we should get the ThoughtWorks management to give their monthly update reports in this format which would certainly be fascinating to see.

Written by Mark Needham

February 26th, 2011 at 4:39 am

Posted in Communication

Tagged with

Espoused theory, theory in action & hypocrisy

with 4 comments

Earlier in the year I wrote about Chris Argyris’ espoused theory and theory in action and one of the interesting aspects to it which I hadn’t previously considered is how we treat people when their espoused theory and theory in action don’t match.

My tendency is to think that these people are hypocrites but Benjamin Mitchell pointed out in a conversation on twitter that it’s not really helpful to think that way:


I find it hard to accept that other’s can’t see the ‘obvious’ gap I can between what they say and what they do (cf fund. attribution error)


@benjaminm I have the tendency to believe they are a hypocrite but I think it’s just an espoused theory/theory in action gap


@markhneedham I think that’s the challenge I’m finding: allowing that people have a gap they are blind to, and not punishing them for it

A typical example where I’ve seen this happen is where someone (we’ll call them person A) teaches a group of people how to give effective feedback, probably by following some of the ideas from Pat Kua’s ‘Tightening the feedback loop‘ presentation.

The implicit assumption in the people being taught is that since person A taught them how to give feedback, person A should be able to give feedback perfectly every time.

Almost inevitably that tends not to be the case and there will be a time when person A ends up giving feedback which isn’t effective and is more a reflection of them than the person they’re supposedly trying to help!

If person A is working in a reflective mindset then hopefully they’ll realise their mistake and work on closing the gap between their espoused theory and theory in action.

If that doesn’t seem to be happening then we need to describe our observations to person A, discuss those observations and help person A improve.

A substantial part of William Noonan’s ‘Discussing the Undiscussable‘ is devoted to coming up with ways that we can deal with these conversations more effectively.

The learning from this for me is that just because someone teaches you something or talks about a topic very passionately that doesn’t mean that they’ve have to be perfect at it!

Written by Mark Needham

February 23rd, 2011 at 1:34 am

Posted in Communication

Tagged with

Communication: Listening

with 3 comments

I realised a couple of weeks ago while pairing with a colleague that I’ve become quite bad at interrupting people while they’re speaking.

I did have an inkling that I’d let my ability to properly listen to someone drift a bit but I hadn’t seen any evidence until my colleague pointed it out.

Somewhat ironically I actually wrote a post about active listening when I first started working at ThoughtWorks in 2006 and reading back over the listening barriers that I listed I realise that there are a few that I tend to break:

Filling-in: You don’t let the other person finish her sentence; instead you finish it for her.

Daydreaming: You get triggered by something the other person says and you’re off in your own world. You don’t have a clue what the person said to you.

Rehearsing: Rather than listening, you are mentally preparing what you are going to say. You might look interested, but you’re really concentrating on planning how you’re going to respond.

I find it really hard to understand what someone is saying purely by the words so I create images in my head based on what’s being said.

My tendency is then to just say what I’m thinking without actually realising that I’m going to interrupt the other person.

Of course that’s because I wasn’t totally listening because I was visualising what they were saying.

I feel that I still need to do this in order to understand what someone is talking about but I’m practicing keeping my thoughts to myself and then vocalising them if necessary when the other person has finished speaking.

The challenge for me is that when I try really hard to not break any of these barriers I’ll often end up being pretty silent when the person is speaking to the point where it might seem that I’m not interested in what they’re saying.

Written by Mark Needham

February 20th, 2011 at 6:43 pm

Posted in Communication

Tagged with

‘Why’ often unhelpful

with one comment

Something which I’ve noticed recently in particular when interviewing people but also in some other situations is that frequently posing a question which begins with ‘why’ results in quite a defensive response.

While discussing this with Priyank he pointed out that asking a question in this way can often be construed as a criticism of the idea being questioned.

Admittedly it is often the case that I’m questioning something which has been done differently than what I might have done but I’m still curious as to the reasoning behind it.

Unfortunately this style of questioning often stops any reasonable discussion from happening which isn’t my intent.

I’ve been reading Sleight of Mouth recently which suggests the following:

Why questions, for instance, often presuppose other judgments, which can lead back into conflict or disagreement.

In general, ‘how’ questions are most effective for refocusing on an outcome frame or feedback frame.

William Noonan has a similar thing to say in Discussing the Undiscussable:

Quality inquiries generally don’t use Why questions because such queries tend to make listeners feel pressured to prove their point or justify their position.

Asking questions starting with “What,” “Where,” and “How” elicit more descriptive responses, and result in more concrete information.

To give a recent example, in India people are currently collecting feedback and one part of it requires the feedback giver to rank the other person in terms of how well they ‘performed’ compared to what the feedback giver expected.

I asked why it was necessary to do that and didn’t really manage to discover the intention very successfully.

Priyank suggested that I might have been more successful if I had asked ‘what’ the intention of ranking the person was instead.

Hopefully I’ll remember that the next time I want to inquire about something but at the moment the ‘why’ question is the one that comes to the fore when I want to do that.

I don’t think it is necessary to use what is a bit of a convoluted style of communication with everyone.

A lot of the people I’ve worked with are quite comfortable with ‘why’ questions being thrown around and I think this style of inquiry is more acceptable when you have trust with the other person.

If the conversation isn’t about something which could be construed as criticism of either person then asking ‘why’ seems to be fine as well.

Written by Mark Needham

February 3rd, 2011 at 6:51 pm

Posted in Communication

Tagged with

While in India: Osmotic communication

with 2 comments

One of the things that has been puzzling me during my time in India is the amount of time that is spent in meetings pushing information to people rather than them pulling it.

In previous projects that I’ve worked on a lot of the knowledge was moved between around as a result of osmotic communication

Osmotic communication means that information flows into the background hearing of members of the team, so that they pick up relevant information as though by osmosis.

This is normally accomplished by seating them in the same room.

Then, when one person asks a question, others in the room can either tune in or tune out, contributing to the discussion or continuing with their work.

After thinking about it a bit more I’ve identified a few reasons why I think this approach doesn’t work so well on my current project.

The ability to ignore background noise

The ThoughtWorks Pune office is pretty much one big room with over 100 people in it so the amount of background noise is fairly constant.

When we’ve tried to run our standup near where we sit it’s been impossible to hear people standing 5 or 6 metres away from you.

You therefore end up getting into the habit of blocking out anything going on around you as was evident when there was drilling being done in the office.

The side effect of doing this, of course, is that there could be relevant discussions going on around you and you’d be much less likely to notice.

Team size/distribution

The second problem is that the team is distributed which means that we’re never going to overhear any conversations in Chicago and vice versa.

To add to this our team is now 25+ in size so it’s spread out over 3 tables one of which is only within shouting distance.

Martin Fowler wrote an article about team rooms quite recently and while the ideas make sense I’m not sure how they scale as team size increases.

Overlap of roles

Although this by no means applies to everyone that I’ve worked with I’ve noticed a tendency for people to stick to their role much more than I have in other countries.

Therefore a developer will only do ‘developer tasks’ and a QA will only do ‘QA tasks’ for example.

When you have overlap such that a developer may be ‘pairing’ with a QA or BA on something then the types of conversations that are head seem to lead to information moving around the team more effectively.

Written by Mark Needham

January 24th, 2011 at 3:33 am

Posted in Communication

Tagged with