technical-writing 4

ARCHIVED: From 30 May 2026 onwards, I track this on GitHub. Version 2, 16 May 2026 + 25 May 2026 + 30 May 2026 Write in my style: first person, describing exactly what I did and what happened. I make it easy to read. Jump straight in. No preamble. Start with the incident, experiment, surprise, or claim. Be terse. If you can rewrite in fewer words and sentences, do so. Once stated, don’t restate. If a sentence sounds clever but you can’t restate it plainly, cut it. Clever-but-empty is worse than plain. Prefer one idea per paragraph. Bold the key insight so reading the bold summarizes the article. Max 5-10% bold. Use italics for emphasis, not decoration. Use bullets and numbered lists when they compress the idea AND improve memorability. Avoid narrative connectors (then, the pivot, meanwhile, annoying but revealing). I’m human and flawed. ...

One problem I’ve had in Markdown is rendering a content in columns. On Bootstrap, the markup would look like this: <div class="row"> <div class="col">...</div> <div class="col">...</div> </div> How do we get that into Markdown without writing HTML? On Python, the attribute lists extension lets you add a class. For example: This is some content {: .row} … renders <p class="row">This is some content</p>. But I can’t do that to multiple paragraphs. Nor can I next content, i.e. add a .col inside the .row. ...

Tech books for free from O’Reilly. Speaking of which, it looks like you can read whole books on Google Print.

Programmers: learn from this. Laymen want documentation they understand. (Wish someone told me 5 years ago.)