Continuing with chapter one, section seven (7) on communication. Thomas and Hunt offer advice on how to be a better engineer by communicating more effectively.
The section begins by advising that it’s “not just what you’ve got, but also how you package it”. They caution that even the best code or ideas are useless unless other people are aware of them.
Developers create various forms of communication, including in meetings, through written code, proposals, and reports. When preparing non-code communication, treat your native language like a programming language by honoring the DRY principle and leveraging automation. Automation in this case can include any documentation templates.
For code, inline documentation should focus on why a decision is made. It shouldn’t explain how because that’s what the code is for.
- Know your audience: They caution, “just talking isn’t enough”. You must understand the needs and capabilities of your audience, and request audience feedback to gauge their level of understanding and engagement.
- Know what you want to say: Create a plan for what you want to say to ensure it expresses what you want in all communication types, including verbal communication.
- Choose your moment: Figure out if your audience is receptive to your ideas before you start sharing them by understanding their priorities.
- Choose a style: Understand how your audience wants the information delivered – a formal document, quick details, or a verbal discussion.
- Make it look good: A good-looking document matters, so take the time to edit and format your communication to make an impact.
- Involve your audience: Get readers engaged early in the documentation process.
- Be a listener: Listen to others as you would have them listen to you.
- Get back to people: Whether it’s email, social media, or documentation comments, there’s no excuse not to respond.
Documentation Best Practices
They nicely devote a separate section for documentation, and as a fan of technical writing, it pleased me to see it.
- Don’t waste time documenting how in your code, document why.
- Comment source code to explain parts of a project or engineering trade-offs.
- Plan your documentation from the start, not as an afterthought.
It’s generally understood that we all need to communicate better. It’s a persistent challenge given all the other priorities we face every day. But it’s worth taking the time to communicate effectively. These engineering communication tips are shared with a voice of experience from both authors.