I found a great meme on Reddit that made me think of software documentation (probably because I think a lot about good documentation and communication).
It can be so hard to know the context that the audience will have when they read something, and I think it’s especially hard to know what can be “too obvious” to write (but might not be obvious to the reader). I think this can be especially challenging with super-strong engineers with deep domain expertise.
I always love a good cooking metaphor, and there was a comment that mentioned how we all do this today, maybe without realizing. When we look at a recipe for chocolate chip cookies, and it says to add an egg, we all know it means a chicken egg. We also know it doesn’t mean a duck egg, or an ostrich egg, or salmon roe.
This idea is core to communication, and I think it shows up a lot when writing technical documentation. It can be challenging to ensure that documentation is useful as a software feature matures. In as little as a few years, there can be subtle “aging” of the documentation, or the product, or the team, which makes the communication harder. This idea is especially highlighted by a project to communicate a message over 10,000 years like “we buried nuclear waste here, don’t dig it up”.