Tenets of Storytelling: How to Write a Technical Proposal

Sophie Alpert recently posted her internal policy on the acceptable use of AI for writing technical documents, which included this line:

More time should be spent authoring a document than consuming it.

Similarly, Over at The Marginalian Maria Popova has been posting about reading more and writing better.

This week, she posted Kurt Vonnegut’s 8 Tenets of Storytelling, which includes a similar line:

Use the time of a total stranger in such a way that he or she will not feel the time was wasted.

Vonnegut’s tenets can teach us something about technical writing, especially these days when an LLM can generate a seemingly polished technical document in seconds.

I’m sure Vonnegut would loath being a technical writer and despise being quoted for technical writing.

Nonetheless, here are Vonnegut’s eight tenets rewritten by yours truly as tenets for writing technical proposals. Unsurprisingly, some of these tenets work, word-for-word.

1. Use your colleagues’ time wisely. They will thank you for it.
2. Give your audience at least one thing to be excited about.
3. Every component should do something useful, even if only to write a log.
4. Every sentence must do one of two things — reveal details or propose action.
5. Start as close to the solution as possible.
6. Be a Sadist. No matter how much you or your team love a feature, show its faults so you can make good decisions.
7. Write to please just one person. If you solve every technical problem, your proposal will get pneumonia.
8. Give your readers as much information as possible as soon as possible. To hell with suspense. Readers should have such complete understanding of what is going on, where and why, that they could finish the design themselves, should entropy degrade the last few bytes.