Java was famously promoted with the idealistic Write Once Run Anywhere and simultaneously derided with the sardonic Write Once Debug Everywhere. Neither is correct, of course, but the idea that one implementation can work for all consumers continues to be attractive, and the fact that it doesn't continues to frustrate.
Nowhere is this truer than as a reader of someone else's awful ticket, PR description, wiki page, code comment, or README: write once, WTF everywhere. And, unfortunately, we've all been there ... on both sides of the problem, sometimes as the author and, months later, confused recipient of the same miserable text.
Which is where today's post comes in. Last year's Heuristics for Working Today was a presentation I gave at work listing nine practices that I find generally useful, one of which I called The Author Pays.
It's the idea that since much of what is written is read multiple times, it seems reasonable in general for the author to pay the cost of making it understandable once rather than every reader to pay every time they come to it.
It's good team play, it's considerate, it encourages a culture of caring for and about one another, of respecting each other's time and effort, it helps us understand what we're writing better, and it improves the quality of the written material that we produce. It's also the kind of thing that can become second nature over time, which naturally lowers the cost.
Anyway, for whatever reason, it struck a chord with my colleagues and so I prepared a deeper look at that one heuristic, and that's the slide deck below.