Communication

Communication has two parts: the medium, and the matter.

The medium is about the people. There's a speaker who provides information, and a listener who receives it. What counts as information in the minds of the speaker and the listener – the structure, the raw data, whatever – don't have to match (it's not just copy and pasting a file), but both people have to be able to use the information, to have understanding and be able to make predicitions based on it. The more compatible the speaker and listener's mental models, the less work is required to break the information down to a common denominator.

The third component, after the two mental models, is a shared language. The more similar the mental models, the more specific (and, hopefully, efficient) the language can be. We use things like education and training and mentorship to build common mental models and to learn specialised languages for information sharing.

The matter is about whatever it is the information describes; the object or system or concept that is being understood. To be able to communicate, both the speaker and the listener have to be able to hold that information in their own mental models. The more accurate the mental model, the more useful the information it holds. And generally speaking, a model's accuracy is based on detail and specificity – more specific: more accurate. So a thorough understanding of the topic is critical for successful communication.

Software development is all about communication. Someone has a problem they have to communicate to the developers (bug tickets, problem statements, requirements docs); developers build a solution that they have to communicate back (manuals and training); developers also have to communicate with each other (design docs, code comments, API descriptions). You might even say that developers have to communicate with the computer, specifying data and algorithms in a model compatible with the computer's storage and processing systems. At every point there is some information that has to be communicated, which means having understanding and using shared languages and models.

In cases of interactive communication the burden of actually transforming the information between mental models and languages can be negotiated and adjusted (often implicitly); however in offline communication (i.e. anything static, like documentation and code comments) the burden falls entirely on the speaker. They can make contextual assumptions about the listener's mental models and languages (consider a theoretical programmer reading your comments vs an end user reading your manual) however it's entirely the speaker's responsibility to transform the information from their mental model into that shared language at an appropriate level.

The ability to communicate with people whose mental models are different from your own is a specialist skill, that's why we have distinct titles for business analysts and technical writers and trainers. We shouldn't necessarily expect developers to write manuals.