Episode 254 - Communication Patterns with Jacqui Read | Summary

Communication is often cited as one of the most crucial skills in software development, yet it’s frequently overlooked in favor of technical expertise. In this comprehensive exploration of communication patterns, we’ll dive into insights from Jacqui Read, author of “Communication Patterns” and experienced software architect, who shares valuable strategies for improving how we communicate in software development teams.

The Importance of Visual Communication

One of the fundamental aspects of technical communication is creating effective visual representations, particularly diagrams. Read emphasizes several key principles:

1. Consider Your Audience

Before creating any diagram, consider who will be using it and what information they need. Even technical artifacts like C4 diagrams can be valuable for non-technical stakeholders when presented at the appropriate level of abstraction.

2. Use Clear Notation

• Always include a legend or key to explain the meaning of symbols, arrows, and boxes.
• Don’t assume viewers will understand implicit meanings
• Avoid relying solely on color to convey information (considering that approximately 4.5% of the global population has some form of color blindness)

3. Maintain Representational Consistency

When creating multiple diagrams or documentation artifacts, ensure clear connections between them. This helps viewers understand relationships and navigate between different levels of detail.

Documentation Best Practices

Read suggests several strategies for creating and maintaining effective documentation:

1. Structure Information Hierarchically
   • Keep high-level information separate from detailed implementation specifics
   • Focus on content that changes less frequently at higher levels
   • Link related pieces of documentation together
2. Mark Documentation Status
   • Clearly indicate when documentation is outdated
   • Include the dates of the last update
   • Make it obvious which sections are actively maintained
3. Automate Where Possible
   • Use tools like OpenAPI for API documentation
   • Consider implementing documentation as code
   • Automate timestamp updates

Remote Communication Strategies

With distributed teams becoming increasingly common, effective remote communication is crucial. Read offers these recommendations:

Email Communication

1. Front-load Important Information
   • Put the most critical information at the beginning
   • Use clear subject lines indicating action required
   • Structure content in order of importance
2. Assume Good Intentions
   • Written communication can be easily misinterpreted
   • Always assume positive intent when reading messages
   • Respond professionally regardless of perceived tone

Knowledge Sharing

Rather than relying solely on documentation, Read advocates for a balanced approach to knowledge sharing:

1. Collaborative Activities
   • Implement pair programming
   • Use techniques like “bytesize architecture sessions”
   • Encourage group documentation efforts
2. Balance Documentation Types
   • Maintain high-level architectural documentation
   • Document critical workflows and recurring issues
   • Find the right balance between documented knowledge and tribal knowledge

Getting Started with Communication Patterns

For those looking to improve their communication skills, Read recommends:

1. Start with Fundamentals
   • Focus on audience awareness
   • Implement basic patterns consistently
   • Add more advanced techniques gradually
2. Choose Your Focus Area
   • Identify specific areas for improvement
   • Select relevant patterns to implement
   • Practice and refine your approach

Conclusion

Effective communication is a learnable skill that goes beyond natural talent or personality type. By implementing these communication patterns systematically, anyone can improve their ability to share information and collaborate effectively in software development teams.

Remember that while these patterns may seem obvious once explained, their consistent application is what makes the difference between effective and ineffective communication. Start with understanding your audience and their needs, then build up your communication toolkit from there.

The key to success is not trying to implement everything at once, but rather focusing on fundamental patterns and gradually expanding your communication capabilities as you become more comfortable with each technique.