Communication

17 October 2019 by Phillip Johnston • Last updated 25 October 2021

Communication is a foundational skill that applies to most human endeavors. Engineering, programming, and product development are no exception. We continually apply our communication skills, whether we work as a team, write documentation, comment code, take notes to remember things later, report issues, or market the product.

Table of Contents:

  1. Working on a Team
  2. Providing Feedback
  3. Running Effective Meetings
  4. Written Communication
    1. Effective Email
    2. Issue Reporting
    3. Pull Requests
  5. Documentation
  6. Books

Working on a Team

As engineers, programmers, and product developers, we rarely work alone. Getting a product out the door usually requires multiple individuals to share the same goal and coordinate execution.

A foundational book for those who are new to working on a professional engineering team is The Unwritten Laws of Engineering. Originally published in 1944, the book has been recently updated with a revised edition (Phillip only read the original, so we cannot make any claim to the value of the revised edition).

The first section of Unwritten Laws is related to teaching beginners what they need to learn about working with a supervisor, colleagues, and outsiders. The third section oft he book contains additional information about personalities and workplace behavior that can be useful for those new to navigating the workplace.

You can learn more about working on a team by reviewing the Managing Your Career entry.

From Around the Web

Providing Feedback

As engineers and programmers, we are constantly giving and receiving feedback. This is not a natural process, and it is extremely easy to destroy someone’s motivation with a poor comment.

For more information, see the entry on Giving and Receiving Feedback.

Running Effective Meetings

Most meetings we’ve participate in are a waste of time. This does not mean that meetings should be completely discarded. They simply need to be focused for improved results.

You might think that meeting effectiveness is a strange topic to highlight. Consider these quotes from Jason Fried:

First, there’s no such thing as a one hour meeting. Basic meeting math applies to all meetings: The time blocked off doesn’t equal actual time spent. The time spent is the time blocked off multiplied by the number of people in the meeting. So, a one hour meeting with 6 people is a six hour meeting. A 15 minute minute meeting with 9 people is a two-and-a-quarter-hour meeting. Even a 15 minute meeting with 4 people costs an hour of collective work time.

Factor in salaries and hourly rates, and meetings get expensive quick. Add in attention diverted and the cost goes up even more. Was that last meeting you had worth it? I’d almost certainly bet it wasn’t. Still not convinced? How would you feel if you had to regularly expense $1200 so you could “tell a few teammates something”. Think that would go over well?

Whenever possible, avoid meetings. Meetings force everyone to stop their work and be present, even if what they were doing was more valuable than the meeting itself (and it often is). Use alternative communication methods and resort to meetings when progress isn’t being made.

To improve the effectiveness of meetings, we recommend:

  • Sending out a written agenda ahead of the meeting (ideally with the invitation)
    • Your meeting should have a specific problem that needs to be moved forward by the end of the meeting
  • If you need someone to contribute something to the meeting, inform them ahead of time about exactly what you need and ask them to come prepared
  • Come prepared to the meeting yourself
    • If you’re not prepared, defer the meeting
  • Make the meeting as short as possible
    • We default to 15 minute durations for our meetings
  • Include only the bare minimum number of people who will positively contribute to moving the problem forward
    • The more people included in a meeting, the more time and money the company loses
  • Take notes during the meeting
  • End the meeting with a solution or decision, as well as the individuals responsible for the solution
    • This identifies a true waste of time: either the attendees weren’t prepared, you weren’t prepared, or the topic was not important enough to call a meeting for
  • Send out notes after the meeting
    • Include important notes summarizing the meeting’s outcomes
    • Highlight any action items that were identified during the meeting
    • Put timelines and due dates for next steps in the meeting notes
  • If you have a recurring meeting, cancel the meeting if a written update would suffice
    • If you’re an attendee, ask the organizer if you can skip unless there is something specific you’re needed for

For more on meetings from around the web:

Written Communication

When Phillip was in college, a significant amount of time in his Computer Engineering program was dedicated to technical writing. Most of the students complained that it was a waste of time. However, once Phillip entered the workforce he realized that 80% of his time was spent communicating with others.

We often have vague notions in our heads, and attempting to effectively communicate those notions to others can be difficult. Writing forces us to clarify our thoughts and exposes holes in our thinking.

Writing is not a natural skill, and it requires practice and regular feedback to improve. If the opportunity is available, we recommend taking a writing class or joining a writing group.

Written communication can take many forms, but the most common ones we encounter are:

  1. Email
  2. Issue Reporting
  3. Pull Requests

Effective Email

Even in the days of Slack, email tends to be the lifeblood of business communication. Aside form internal communication uses, email is the primary way we communicate with external contributors, partners, and vendors. Improving our email habits has a dramatic impact on our day.

Our general tips for effective emails are:

  • Use a descriptive and meaningful subject line
  • Keep the message as short as possible
    • People tend to ignore long emails “until I have time to focus”, which invariably never comes
  • Be polite and formal
  • Think about ways your tone can be misinterpreted and adjust accordingly
    • Are you trying to be too brief? Perhaps you will sound curt and demanding
    • Without body language, sometimes additional sentences are needed to soften a message and give the correct tone

As with meetings, don’t send an email if another form of communication (such as a phone call) would be more effective, especially if there’s a chance for an emotional reaction.

From Around the Web:

Issue Reporting

Every project has problems. Every project needs a way to report and manage those problems. Everyone who has worked with an issue reporting system can tell you dozens of horror stories about horrible bug reports that they couldn’t work with.

Writing a great issue report is a skill that every engineer and developer should master.

Here’s our guidelines for writing a great issue report:

  • Each report should describe a single issue
    • Break multiple issues up into separate reports, even if they are related
  • Provide steps to reproduce the problem
  • Provide information about your environment, including hardware version, software verson, OS version, and any other relevant information about your setup
  • Describe the expected results for your scenario
  • Describe the actual results observed
  • Comment on reproducibility – does it happen every time? once in a million?
  • Describe the impact that the issue has on customers/you/the company
  • Identify any workarounds you found

From Embedded Artistry

From Around the Web

Pull Requests

Pull Requests and other merge management strategies are common on modern software projects. Rather than allowing contributors to directly commit to master, the change must be proposed and reviewed through automated and manual processes. Writing effective pull requests descriptions will allow the other contributors to process your Pull Request more quickly.

From Embedded Artistry

From Around the Web

Documentation

Documentation is a critical part of professional engineering work, even if it’s unpopular. Without documentation:

  • Users cannot understand how to use our system
  • New developers require hand-holding to learn about the new system
  • Interested contributors have no idea how to help
  • Our future selves won’t remember why we made specific decisions, how the system functions, or how the product is supposed to be built

To familiarize yourself with different documentation approaches and techniques, see the Documentation entry.

Books

You can support the website by purchasing books through our Amazon affiliate links:


The Unwritten Laws of Engineering
by W.J. King
Related Terms:

Share Your Thoughts

This site uses Akismet to reduce spam. Learn how your comment data is processed.