How to Write Effective Technical Blog Posts: Practical Tips for Programmers

What is a technical article

A technical article is any piece that discusses programming or software development topics. It can be original, a translation of existing English content, an analysis of a specific problem, or a series such as a tutorial.

Why write technical articles

Common motivations include personal note‑taking, helping others, building a knowledge base, monetisation, and raising one’s profile. While helping others is essential, authors must ensure accuracy to avoid misleading readers. Accumulating knowledge requires deep mastery of the subject, and long‑term high‑quality output is needed for monetisation or becoming a recognized expert.

What makes a good technical article

A good article should answer readers' questions in an easy‑to‑understand way. It gains credibility when readers see positive comments and engagement before committing to read the full text.

Choosing a topic

Topic selection influences readership and can be driven by two approaches:

Reader‑oriented: tutorials on new technologies (e.g., Android Studio series), popular tools, thematic series (e.g., memory‑leak deep‑dives), or “soft‑skill” pieces that attract many readers.

Personal‑research‑oriented: niche technical details such as the inner workings of ThreadLocal.

Clear structure matters

A well‑organized article prevents readers from feeling overwhelmed. Using Markdown headings (e.g., #, ##) and bullet points helps maintain hierarchy. Example structure:

## Section Title
* abc
* def
* ABC
* DEF

Additional tips: avoid overly long paragraphs and insert blank lines between sections.

Code highlighting respects readers

Technical articles should include code snippets, and those snippets must be syntax‑highlighted to improve readability.

Gathering feedback

Enable comments on the publishing platform to collect useful feedback such as errors, alternative solutions, praise, and constructive criticism.

Time investment

Writing a quality blog post typically involves two phases:

Research phase – reading documentation, StackOverflow, and English blogs, and breaking the topic into sub‑points (e.g., purpose, usage, internal implementation of ThreadLocal).

Writing phase – converting research into structured text and images.

Most authors write during weekends and early mornings (around 6 am) to minimise interruptions.

Dealing with procrastination

Common procrastination behaviours include browsing news, social media, or delaying the start of writing. Overcoming it requires disciplined self‑control and gradual habit formation.

Translation challenges

Translating technical articles from English to Chinese often leads to the “meaning‑but‑no‑elegance” problem. Improving translation skills and reading high‑quality translations are recommended solutions.

Key practices for writing well

Simplify complex concepts.

Maintain a clear, logical structure.

Write regularly to build skill and intuition.

The author’s views are personal and intended to help readers improve their technical writing.