I posted this internally at Google, someone asked me to post it externally. To be frank, I almost didn't write it because it seemed so obvious. But isn't that the point? What's obvious to you might not be to others. So I'm happy to oblige.
Maybe this is obvious, maybe this is so generic that it's useless, but I feel it has to be written somewhere.
The time you spend on communicating something (writing a doc, an email, a bug, a comment, ...) should be proportional to the "distance" of the person receiving the message.
Distance varies on three axes I can think of:
- Physical: This one is obvious, but requires some explanation. If someone is far away from you, your bandwidth is hugely limited already. You speak to them less often, they don't get your body language, they don't get your tone, they don't get you. Make things easy for them.
- Subject matter: The less someone knows about (your project, this topic, your likely state of mind), the more you should explain. Good communication is a lot about empathy. Get in their shoes. How hard or easy is it to understand "The PMDS is a gRPC server which also supports hermetic access"? What if you don't know what's PMDS? Or hermetic? Or gRPC?
- Time: This one is tricky. Spend more time on a message that will be read by a person in the future (for example, a comment explaining an obscure if-clause you're adding to the bowels of some ancient codebase). The future is funny in that it's unpredictable. Google's lingua franca might change. Things that are obvious now will be forgotten by then. The brand new framework you're writing will be doubly deprecated and considered the old ugly.
Spend extra time explaining things to the people in the future. They might be dealing with a much broader scope than what you can imagine today. They might not know what you know now. They might be dumb. They might be all these things. And, especially, they might be you.