Message Ina Bottle

The basic metaphor of a message in a bottle is very simple: you put some writing on a piece of paper, stuff it in a bottle, put a cork in it, and chuck it into the ocean. Sometime later, someone finds the bottle, takes off the cork, pulls out the paper, and attempts to read the writing on the paper. Any (conventional) manual of writing style will tell you that you have to consider your audience as a factor when you write. Yet with the message in a bottle, the idea is that you have no idea who will pick it up and try to decode it. It would be nice if they knew the language in which you wrote, but even that isn't completely certain. Perhaps it winds up among people in a foreign culture, with a different language, but that one person in the tribe has some facility with foreign speech and is given the message for interpretation. The message of the metaphor is that you should consider as if you are writing for him and that you should break things down so as to be as precisely understood as possible to the largest number of people possible.

Write like this. First, keep ideas simple. A simple idea is easy to understand. Ideas that are not simple are hard to understand. Because of this, it is harder to see that it is wrong when it is wrong. With simple ideas, you or someone else is more likely to see any problem. Second, use common words. A vocabulary is how many words a person knows. But vocabulary itself is not a common word. Some people know less words than you. In English, there are maybe one thousand to two thousand common words. Use these when you can, and more people will understand the words. Third, use simple statements. Your ideas are already simple. So why write as if they are very complicated? Don't! It helps to write it in the same way you would say it. Just say what you mean and nothing more. If you do these things, people will understand what you write better.

• Re: "A simple idea is easy to understand. Ideas that are not simple are hard to understand." - This is not true. Simple ideas are hard to understand... unless you already know them. Examples of simple ideas include recursion, monads, complex numbers, category theory, relativity, and so on. Understanding even very complex ideas constructed of simple parts already understood is often much easier than understanding even one 'new' simple idea. When writing for a broad audience, it is better to aim for 'keep ideas in the lowest common denominator of shared experience' than it is to 'keep ideas simple'.

The first paragraph was written in a minute. The second paragraph was written in ten minutes. Concise writing is a skill, as is fluent and ornate writing, but generally those who can do both find that the former takes more effort. This is likely because these smart people think in a complex "stream of consciousness" sort of way and translate this into their writing habitually. Making the ideas so expressed into something concise and easy to parse, without losing information, is an editing chore and is not easy.

The applications to writing software should be obvious. Your first pass at writing code, particularly when you are attempting something that seems complex, will not be particularly readable in most cases (or correct at all). Yet you cannot be satisfied with something that is readable to you, the original coder, at the time. Your code very literally is a "message in a bottle" if thrown on the seas of the Internet, so you have to consider future maintainers. And even your own code can seem foreign if it is from some years prior. So design it to be readable, when possible, by that barely-literate elder in a faraway fishing village. Or, to unpack that metaphor, by someone who has been hacking on your framework (programming language, operating system, etc.) for only a short period of time. --PeterKirby

Writing code for maintainers means writing it not with simple ideas, but rather with the lowest-common-denominator of commonly understood components. This often requires expressing your code in lower-level manners - i.e. no using FunctorObjects unless they are already in common use in the community, and no using 'withResource(resourceID,action)' blocks to simplify automatic cleanup unless people also know this pattern. While maintainability of code is a relevant consideration for language and framework design, I don't believe writing your code to support PlugCompatibleInterchangeableEngineers is the best way to achieve it. Alternative approaches include LiterateProgramming or careful design of the traditional IDE.