| name | technical-blog |
| description | A framework for producing high-quality technical blog posts that balance technical depth, readability, and professional rigor. |
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
- Define the topic, reader, and learning goal.
- Research existing content and identify the best angle.
- Build an outline before drafting.
- Gather reliable examples, code, screenshots, or references.
- Draft first, then edit for clarity, accuracy, and structure.
- 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.
