technical-blog-writing

Start with a TL;DR, state the problem concretely, present the solution with runnable code examples, and include results with specific numbers. Follow the tutorial, deep dive, postmortem, benchmark, or architecture structure depending on your post type.

Show the end result first, list prerequisites explicitly, walk through numbered steps with runnable code blocks, link to the complete code repository, and end with next steps. Every code block should be copy-paste-runnable with pinned dependency versions.

Word count depends on type: quick tips run 500-800 words, tutorials 1,500-3,000, deep dives 2,000-4,000, architecture posts 2,000-3,500, and benchmarks 1,500-2,500 words where charts carry the load.

The writing guidelines and templates work standalone, but generating header images, architecture diagrams, and benchmark charts requires the belt CLI from inference.sh. Install it and run belt login before using the visual generation commands.

Common mistakes include missing TL;DR summaries, broken code examples, unpinned dependencies, condescending words like 'simply' or 'obviously', marketing tone, and no trade-offs section. Always test code blocks and discuss limitations honestly.

Publish on your own blog first, then cross-post to Dev.to and Hashnode with canonical URLs pointing back. Submit to Hacker News and relevant subreddits, and share a summary thread on Twitter/X or LinkedIn.