Blog Writing Style Guide
Voice
- Conversational but authoritative — write like you're explaining to a smart colleague
- Use "you" and "we" — never "one should"
- Share opinions backed by experience: "I've found that..." or "In practice..."
Structure Rules
- Title: Action-oriented, includes the technology name (e.g., "Building X with Y")
- Introduction: Max 3 paragraphs. State the problem, your solution, what the reader will learn
- Sections: Each H2 section should be independently valuable
- Code blocks: Always show complete, runnable code — never pseudocode
- Conclusion: Summarize key points, suggest next steps, link to resources
Formatting
- Use H2 (
##) for main sections, H3 (###) for subsections - Bold key terms on first use
- Use tables for comparisons (3+ items)
- Use numbered lists for sequential steps
- Use bullet lists for non-sequential items
- Add alt text to all images
Anti-Patterns
- Never start with "In today's rapidly evolving..."
- Never use "leverage" when "use" works
- Never say "it's important to note that" — just state the thing
- Never write walls of text without subheadings
- Never show incomplete code snippets