Writing guide for better posts
This is a living document I use to archive my techniques for effective
web-based communication. Future Jacob is the only target audience, but
you're welcome to read along.
Cheat Sheet
The outline should generally follow the simple structure of what, why, how. Make sure the following questions are answered, preferably in order, not necessarily in separate sentences. The word 'introduced' specifically refers to information that is unfamiliar to an average reader.
- What
- What is the topic?
- What am I introducing to the reader?
- What did I do?
- What did I investigate?
- What did I achieve?
- Why is this hard (if applicable)?
- Why was the result interesting?
- Why was the topic interesting?
- Why did I decide to investigate this?
- How did I do the thing?
-
How does it work?
- What are the domain-specific keywords and knowledge do I expect the reader to know?
- What are the domain-specific keywords and knowledge do I don't expect the reader to know?
- Do I first introduce (not explain) the ones they don't know?
- Do I explain them to enough of a degree?
- Is the introduction sufficiently ditinct from the explanation?
- How do I justify the results I observed?
- What did I know at the start?
- What failed along the way?
- What did I learn by the end?
Why
How
Considerations
- How long do I want someone to spend reading the page?
- What might be their three takeaways?
- No passive tense, ideally forbid 'is' and 'be'.
- Leave caveats for the end. They are important but distracting.
- Never lead with a weak hand. Something went wrong? Talk about what you learned, then say why you learned it (something went wrong).
- Prove with examples.
- Show humility, but not through self-denigration
- Stay earnest
Changelog
- January 26, 2024: Started this page after first drafts of articles
- Febrauary 6, 2024: Tons of helpful advice from Matt Estes