The Author Pays

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 consumer 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, 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 this slide deck.

Transcript

1. The Author Pays James Thomas. 2026-10-08
2. Heuristics for Working
3. Visual Noise
4. tl;dr - I am not reading this page of noise Emoji noise What draws the attention here? The link cards, right? @-list noise Link card noise Personal hatred: long raw URLs
5. A Better Way First: key points Clear. Minimal decoration Optional thread for anyone who cares Just delete the distracting cards
6. A “quick” reminder But no-one is reading this.
7. A Better Way Clear call to action What to do if this matters to you Long but clear: Why, When, What, How.
8. Source
9. Reduce Visual Noise • Useful order • Consumable chunks • Don’t clutter
10. What Is It?
11. Is This Really a List?
12. Yes, it’s a List
13. Is This Really a Table? • Intuitive drag-and-drop functionality ◦ ◦ ◦ Customisable: yes Cross-platform: no Can be rendered by all modern engines • Real-time validation ◦ Not cross-platform • Integrate seamlessly with existing systems ◦ ◦ Uses standard comms API Is customisable to a limited extent • Enhanced reporting capabilities ◦ ◦ Cross-platform: no Bundled logger has PHI detection • Automated error handling ◦ Same comms API as earlier
14. Yes, it’s a Table The top-level bullets are features The lower-level bullets are attributes with values Feature Customisable X-Platform Intuitive drag-and-drop functionality Y N Enhanced reporting Y (limited) N API Compatible with modern render engines Automated error handling Bundled logger has PHI detection Standard comms Real-time validation Other N
15. Ah. Now I See That was a Table Too
16. But is Any Table the Right Table? And the other options? And the other options don’t? Two points in one bullet But is it obvious? Bullets waste valuable space Please just delete me
17. No, There are Righter Tables One row per feature Identify the things we care about Cells with the same value for a row are obvious Simple decoration allows high-level comparison across options Empty cells show gaps in the modelling
18. What Is It? • Recognise the type • Choose the right structure • Format for understanding
19. Friction
20. Title disagrees with description Refers to related work but doesn’t link it Someone copypasted this and just changed the title I found the other ticket. But why should I have to?
21. A Better Way Give context Left the ticket better for the next person What failure looks like when we try to re-enable. Example not description. Source
22. There are a lot of stages YOWSA! There are also time dependencies. I want to follow our team process. There are multiple variables: status, assignee, flag. And this looks important but it’s after the table. Should I read it first?
23. A Better Way Important first Still complicated but factors are explicit Colour helps to show relationships
24. Show who needs to do what, and when and why
25. Friction • Contradiction • Inconsistency • Complexity
26. Why Me?
27. The cost/benefit decision • • • • • • • • • How often will it be read? Who will read it? What context will they have? What context can I share? How much time do I have? Whose time is more valuable? Is something needed now? What would be good enough If you’re doing it, maximise its value
28. Summary
29. In general, the author pays • • • • • Important first Minimise noise Appropriate structure Format for understanding Avoid friction