Mark Needham

Thoughts on Software Development

Archive for the ‘Communication’ tag

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

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

TWU: Fishbowl

without comments

As part of a session on ThoughtWorks values at ThoughtWorks Univesity we held a fishbowl to discuss the trade offs we often have to make between the values when confronted with real life situations.

A fishbowl conversation is a form of dialog that can be used when discussing topics within large groups.

Four to five chairs are arranged in an inner circle. This is the fishbowl. The remaining chairs are arranged outside the fishbowl. A few participants are selected to fill the fishbowl, while the rest of the group sit on the chairs outside the fishbowl. One chair is left empty

Any member of the audience can, at any time, occupy the empty chair and join the fishbowl. When this happens, an existing member of the fishbowl must voluntarily leave the fishbowl and free a chair. The discussion continues with participants frequently entering and leaving the fishbowl.

A photo from a Lisa Crispin led fishbowl

We tried a slight variation on this in that we had the people not currently in the fishbowl stand around the outside of fishbowl rather than sitting down in an attempt to encourage participation.

The overall feedback that we got from the session was that it was enjoyable to take part in although it was clear that people weren’t rotating into and out from the fishbowl as frequently as I’ve seen before.

The tone of the discussion was also relatively agreeable and there weren’t any big disagreements between people where they got really fired up in defending their view.

Sumeet pointed out afterwards that the fishbowl is often more effective in facilitating discussion around a topic which people are really passionate about and have strong opinions on.

Since we had only introduced the ThoughtWorks values about 20 minutes earlier this wouldn’t fit into that category.

Interestingly although the trainers had strong opinions on certain topics it was difficult to create a discussion because the grads mostly didn’t have examples to disagree with those points so the discussion became more theoretical/hypothetical.

I do like this format though so we’ll have to try it again with some other topics or perhaps the same one in a few weeks time to see how it works out.

Written by Mark Needham

March 15th, 2011 at 1:11 am

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

Team Communication: Learning models

with one comment

One of the problems I’ve noticed in several of the ‘agile’ communication mechanisms (such as the standup or dev huddle) that we typically use on teams is that they focus almost entirely on verbal communication which only covers one of our learning styles – the auditory learning style.

The Learning Models

The VAK learning style model describes a simple model covering the different learning styles that people have:

  • Visual – seeing and reading.
    • Involves the use of seen or observed things, including pictures, diagrams, demonstrations.
  • Auditory – listening and speaking.
    • Involves the transfer of information through listening: to the spoken word, of self or others.
  • Kinesthetic – touching and doing.
    • Involves physical experience – touching, feeling, holding, doing, practical hands-on experiences.

My own learning style is predominantly visual so I tend to find that a well drawn diagram will help me understand something far more quickly than a colleague spending 10 minutes explaining something using only words.

If the latter happens then I either find myself totally zoning out or mentally trying to sketch out what the speaker is saying.

In a team environment this would translate into ensuring that we use the whiteboard when trying to explain problems.

Sometimes just going to the whiteboard isn’t enough and we need to cater to the kinesthetic learning model which in software development terms would involve walking through the code.

I’ve never been involved in a team session where we went through a part of the code base together but I’ve heard from colleagues that it can be very helpful in some situations.

I think it’s important that we know what our favoured learning style is so that we can guide any discussion in such a way that it plays to our strengths.

In terms of software development

Although people tend to have different learning models my general observation is that we can move through the models from auditory to visual and finally kinesthetic depending on the complexity of what’s being explained.

I think it also partly depends on the experience of team members. For example, I’m now able to understand many more discussions which are purely verbal where previously I’d have needed a diagram or someone to show me what they meant in the code.

I think it’s important to look at the implicit feedback we’re getting from colleagues when explaining something to see whether or not the model we’ve used has been effective.

If it hasn’t then at least we know we have some other approaches to try which might be more successful.

Written by Mark Needham

November 27th, 2010 at 10:50 am