Topic 7: Communication

We spend so much of our day communicating that we need to get it right.

Think of the language you normally communicate with as just another programming language, the authors suggest. You should write in natural language just as you would code: respect DRY (Don’t Repeat Yourself), ETC (Easy to change), automation, and so on

The authors offer a few ideas:

  • Know the audience
  • Know what you want to say
  • timing
  • Make your documents beautiful
  • Engage the audience
  • Do the listener
  • Respond to others
  • Tie code and documentation together

I’d like to pick a few interesting things to say about the above:

1. Know your audience

Communication is the process of conveying information.

To get your message across, you need to understand your audience’s needs, interests and abilities.

Suppose you want to propose a web-based system for end users to submit bug reports.

You can describe the system in many different ways, depending on the audience.

End users prefer to be able to submit bug reports at any time, 24 hours a day, rather than waiting on the phone.

The Marketing Department can take advantage of this feature to promote sales.

Support managers have two reasons to be happy: hire fewer staff and problem reporting can be automated.

Finally, developers may be interested in gaining some experience with web-based architectural techniques or trying out a new database engine.

By canvassing each group appropriately, you can get them all excited about your project. As with all forms of communication, the trick here is to gather feedback. Don’t just wait for the question to come up: ask it.

You can learn what the other person wants by interacting with them. You need to constantly improve your understanding of your audience as you communicate.

2. Know what you want to say

Before formal communication, plan out what you want to say, outline it, and ask yourself, “Is this communicating what I want to say in the right way to my audience?” Refine until you can’t refine more.

3. Pick your moment

It’s six o ‘clock Friday afternoon, and the auditors have been in for a week. Your boss’s young son is in the hospital, it’s raining cats and dogs, and the experience on the way home from work is sure to turn into a nightmare. This is probably not a good time to ask her to upgrade your laptop’s memory. One way to understand what your audience wants to hear is to figure out what their priorities are. When the manager has just been lectured by his boss for missing some source code, take the opportunity to talk to him about the idea of a code repository and he will be more likely to listen.

Before you talk about something, ask: Is now a good time to talk about it?

4. Make your documents look good

As any chef (or food Network host) will tell you, just bad appearance can ruin hours of hard work in the kitchen.

Take a look at the example documentation in the package to learn about styles and layouts. Check for typos.

5. Be a listener

If you don’t listen to them, they won’t listen to you.

Encourage people to talk by asking questions and try to get them to sum up what you said.

By programming the meeting into a conversation, you’ll be able to present your point of view more effectively.

Respect is like a ball. You have to bat it out before it bounces back. One way to show respect is to listen.

6. Tie code and documentation together

Pragmatic programmers see documentation as an integral part of the development process. To make writing documentation a little easier, avoid rework and waste of time and always have it handy — directly in the code.

There is no need to comment each function, data structure, and type declaration separately. This makes code harder to maintain: if you want to change something, your colleagues will need to change the code and comments, and it’s easy to miss the changes when the project is urgent, causing the code and comments to get out of sync.

Limit non-API comments to discussing why they exist and their intentions and goals.

Comments are unnecessary when the code already shows how things are done — it violates the DRY principle.

Annotating source code is a great opportunity to document project details that cannot be documented elsewhere: the engineering trade-offs, why decisions were made, what alternatives were abandoned, and so on.