magicbowen/technical-blog

Technical Blog

Introduction

Use this template for technical blog posts that explain concepts, walkthroughs, or engineering decisions to an external or internal audience.

Background:

• Technical blogs need to balance depth, readability, and trust.
• The output should teach clearly while staying technically accurate and structurally scannable.

Precautions:

• Avoid hype, unsupported claims, or promotional language.
• Define jargon on first use and keep code examples accurate.
• Refer to templates/technical_blog_post.md for the output structure and examples/observability_blog_excerpt.md for a short example.

Writing Rules

Tone

• Professional and clear.
• Authoritative but not overstated.
• Objective and evidence-based.
• Engaging without becoming casual or promotional.

Format

• Use descriptive headings and subheadings.
• Keep paragraphs short.
• Use lists for steps, comparisons, or takeaways.
• Wrap code in fenced blocks with language tags.
• Include visuals only when they add real explanatory value.

Style

• Prefer active voice.
• Keep sentences concise.
• Define jargon and acronyms.
• Use examples and analogies to explain abstract ideas.
• Link to authoritative references when useful.

Audience Awareness

• Adjust depth to the target reader.
• Anticipate likely questions.
• Explain why the topic matters before diving deep.

SEO and Readability

• Use relevant keywords naturally.
• Add a concise meta description when the publishing platform supports it.
• For longer posts, include a table of contents.

Writing Workflow

1. Define the topic, reader, and learning goal.
2. Research existing content and identify the best angle.
3. Build an outline before drafting.
4. Gather reliable examples, code, screenshots, or references.
5. Draft first, then edit for clarity, accuracy, and structure.
6. Format for the target platform and add metadata before publishing.

Companion Files

• templates/technical_blog_post.md: reference structure for the final article.
• examples/observability_blog_excerpt.md: example excerpt showing tone and pacing.