Having a great idea or design is not enough to make your software project succeed. If you want stakeholders to buy into your design and teams to collaborate and contribute to the vision, you also need to communicate effectively. In this practical book, author Jacqui Read shows you how to successfully present your architecture and get stakeholders to jump on board.
Misunderstanding and lack of buy-in leads to increasing costs, unmet requirements, and an architecture that is not what you intended. Through constructive examples and patterns, this book shows you how to create documentation and diagrams that actually get the message across to the different audiences you'll face.
This book shows you how to:
Design diagrams and documentation appropriate to your expected audience, intended message, and project stage
Create documentation and diagrams that are accessible to those with varying roles, needs, or disabilities
Master written, verbal, and nonverbal communication to succeed in technical settings
Apply the communication patterns presented in this book in real-world projects and software designs
Communicate and collaborate with distributed teams to successfully design and document software and technical projects
Author(s): Jacqueline Read
Edition: 2
Publisher: O'Reilly Media, Inc.
Year: 2023
Language: English
Pages: 250
I. Visual Communication
1. Communication Essentials
Know Your Audience
Style Communicates
Mixing Levels of Abstraction
2. Clarify the Clutter
Colour Overload
Boxes in boxes in boxes
Ambiguous Connections
Balance Text
3. Accessibility
Relying on Colour to Communicate
Include a Legend
Appropriate Labels
4. Narrative
Match Diagram Flow to Expectations
The Big Picture Comes First
Clear Relationships
5. Notation
Using Icons to Convey Meaning
Using UML for UML’s Sake
Mixing Behaviour and Structure
Going Against Expectations
6. Composition
Illegible Diagrams
Representational Consistency
Misleading Composition
Create a Visual Balance
II. Multi-Modal Communication
7. Written Communication
Simple Language
Acronym Hell
Structuring Your Writing
8. Verbal and Non-Verbal
Encoding Messages
Decoding Messages
Persuasion
9. The Rhetoric Triangle
Ethos
Establish Your Credentials
Use Trustworthy Sources
Transparency
Demonstrate Your Knowledge
Pathos
Speak from the heart
Use vivid language & strong imagery
Tell a story
Logos
Use data and facts
Make logical connections
Use reasoning and argumentation
III. Communicating Knowledge
10. Knowledge Management Principles
Products over Projects
Abstractions over Text
Perspective-Driven
11. Knowledge and People
Getting Feedback Early & Often
Share the load
Just-in-time Architecture
12. Effective Practices
Using Architecture Decision Records (ADRs)
Effective Architecture Characteristics
All Documentation as Code
Technical Documentation
Other Documentation
Automatically Generated Documentation
IV. Communicating Remotely
13. Remote Time
Synchronise Time
Working Patterns
Energy & Productivity
14. Remote Principles
Meetings to Synch
Async to Think
Remote-First
15. Remote Channels
Symmetrical Email
Online Presentations
Remote Tools & Governance
About the Author
