Writing for readers and retrievers
A practical framework for publishing markdown posts that work for human readers, search engines, and AI systems.
Good technical writing should answer the reader's question in the first paragraph. That same structure also helps search systems and AI assistants cite your work correctly.
Start with a direct answer
Your intro should make one clear claim in plain language. If the reader only scans the first minute, they should still learn something useful.
Use heading structure on purpose
Headings are navigation, not decoration. They should mirror how someone naturally asks the question and how you would answer it step by step.
Make evidence easy to extract
Short paragraphs, lists, and explicit references make your writing easier to quote and easier to trust.