I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Christopher wrapped up the first group of talks before the morning break. His first boss taught him that making sound is not the same as making sense. That concept evolved in his mind to, information is not the same as communication. The standards of music can guide us here.
Since that talk with his first boss Christopher has worked on dozens of types of docs. The metaphor or information and communication has helped him throughout.
The music world defines noise as sound without structure. When you take sound and place it within a satisfying structure you get music. The search for this satisfying structure is innate. When placed in an MRI and given unfamiliar music the intellectual centers of people’s brain light up. They immediately try to make sense of the sound and determine its patterns.
With documentation we tend to accept docs that are failures in the same way as unguided and unstructured noise. But we lack the same fundamental cognitive abilities to identify them. When a document doesn’t communicate it fails. Just like when sound doesn’t exist within a satisfying structure. The likelihood that a document without communication conveys knowledge is extremely low. Ask yourself whether the doc you’re creating contains the necessary information.
Without a theme, and harmony, and a pleasing tempo, you have a document that makes noise. #writethedocs (noise vs. music in documentation)
— Lyzi Diamond (@lyzidiamond) May 6, 2014
Next Christopher talked about deliberate noise. Many times noise is accidental, but sometimes it serves a purpose. The most common lie on the internet is, “I have read and agreed to the terms of service.” No meaningful attempt at communication resembles a terms of service. iTunes, for example, has a 29 page long terms of service.
Music play time equivalent to the time it takes to read the iTunes EULA. #writethedocs pic.twitter.com/vS8ksS9gBV
— Josh Roppo 🌻 (@joshroppo) May 6, 2014
It’s goal is not communication. It’s goal is to protect the legal interests of Apple and to force you to click “I agree” without reading. This is often what noise in documents does; it gets you to acquiesce.
Deliberate noise comes in to play frequently in the legal and government arenas. Documentation noise is treated as unavoidable. But we totally can avoid it! A musical document succeeds by feeding your brain what it craves; it satisfies the innate needs. This music-like satisfaction is more than a nice-to-have, it’s essential.