Make communication part of your job

Overview

Software systems are complex, and large projects have a lot of participants and stakeholders. As engineers, our job is not slinging code - it's understanding problems, designing solutions, and collaborating with others to implement those solutions effectively. All of this requires clear communication.

By spending time to communicate our ideas and intent clearly, we build alignment with our teammates, reduce misunderstandings, and ultimately deliver a better product faster. This isn't about increasing the volume of communication, but about producing artifacts that are broadly useful and easy to understand.

How to do it

• Checked item: Document critical decisions using Architectural Decision Records (ADRs).
• Checked item: Use Markdown and keep documentation close to the codebase.
• Checked item: Illustrate complex ideas with diagrams (eg: Mermaid for clarity).
• Checked item: Use consistent terminology and definitions across documentation.
• Checked item: Use PR descriptions to explain the "why" behind changes, not just the "what."