# Complete Writing Style Guide A comprehensive guide covering three distinct writing styles for technical content: Engineering Blog Posts, Technical Documentation, and Success Stories. ## Table of Contents 1. [Overview](#overview) 2. [Engineering Blog Style (Cursor-Style)](#engineering-blog-style-cursor-style) 3. [Technical Documentation (Anthropic-Style)](#technical-documentation-anthropic-style) 4. [Success Stories & Case Studies](#success-stories--case-studies) 5. [Quick Reference Guide](#quick-reference-guide) 6. [Style Comparison Matrix](#style-comparison-matrix) --- ## Overview This guide covers three essential writing styles for technical content creators: - **Engineering Blog Posts**: Problem-solving narratives that share technical insights - **Technical Documentation**: Task-oriented guides that enable implementation - **Success Stories**: Metric-driven narratives that showcase transformation Each style serves a distinct purpose and follows specific patterns to maximize effectiveness. --- ## Engineering Blog Style (Cursor-Style) ### Core Philosophy Write as if sharing an exciting technical discovery with a smart colleague. Focus on problems, failed attempts, solutions, and honest engineering discussions. ### Key Principles #### 1. Start with the Problem ```markdown Here's a recipe for failure: give a kid a Python textbook, make them memorize syntax for six months, then wonder why they hate programming. ``` #### 2. Structure: Problem → Journey → Solution - **Opening Hook**: Concrete failure scenario or specific challenge - **Failed Attempts**: What didn't work and why - **The Solution**: How you actually solved it - **Implementation Details**: Code, architecture, decisions - **Results**: Honest assessment with real observations - **Open Questions**: Unsolved challenges for the community #### 3. Technical Honesty - Include asterisks for caveats - Walk through failed approaches - Acknowledge limitations - Avoid fake metrics #### 4. Writing Patterns - **"We want to..."** (intentionality) - **"The problem is..."** (direct identification) - **"It turns out..."** (discovery narrative) - **"Can we...?"** (exploratory questions) #### 5. Code Integration ```python # Comments explain non-obvious aspects def shadow_workspace(): """Create hidden window for AI edits""" # Asterisk addressed later* return hidden_window ``` #### 6. Length Guidelines - **2-3 minutes**: Single focused problem - **4-6 minutes**: Problem with solution - **10+ minutes**: Deep technical dive - **19+ minutes**: Comprehensive exploration ### Example Template ```markdown # [Compelling Technical Problem] [One-line description of the challenge] Posted By [Author] [X] minutes read [Opening scenario showing the problem] ## The Problem: [Clear Problem Statement] [Why this matters, what fails without solution] ## Failed Attempt #1: [Approach Name] [What we tried and why it didn't work] ## Failed Attempt #2: [Approach Name] [Another approach and its limitations] ## The Solution: [Solution Name] [How we actually solved it] ### Implementation Details [Code examples, architecture diagrams] ## What We've Observed [Honest results without fake metrics] ## Open Questions [3-5 unsolved challenges for the community] [Email for solutions or collaboration] ``` --- ## Technical Documentation (Anthropic-Style) ### Core Philosophy Enable immediate implementation through clear, task-oriented guidance with practical examples. ### Key Principles #### 1. "When to Use" Pattern Every section starts with practical context: ```markdown When to use: You've been working on a task with Claude Code and need to continue where you left off in a later session. ``` #### 2. Example-First Approach Show the command/code first, explain after: ```bash claude --continue ``` This immediately resumes your most recent conversation without any prompts. #### 3. Progressive Disclosure 1. **Basic usage** (most common case) 2. **Advanced options** (flags, parameters) 3. **How it works** (technical details) 4. **Edge cases** (warnings, limitations) #### 4. Tables for Complex Interactions | Role | Content | | --------- | ------------------------------------------------------- | | User | You're a Customer Insights AI. Analyze this feedback... | | Assistant | { "sentiment": "negative", "key_issues": [...] } | #### 5. Practical Tips Pattern ```markdown Tips: - Start with broad questions, then narrow down - Ask about coding conventions and patterns - Request a glossary of project-specific terms ``` #### 6. Warning Conventions ```markdown ⚠️ IMPORTANT: Never commit API keys directly to your repository! ``` ### Example Template ````markdown # [Feature Name] [One-line value proposition] ## [Primary Use Case] When to use: [Specific scenario] ```bash command example ``` ```` [Brief explanation of what happens] ### Advanced Usage ```bash command --with-options ``` [Explanation of differences] Tips: - [Practical tip 1] - [Practical tip 2] - [Common gotcha to avoid] ## How it works [Technical details for deeper understanding] ## Next steps - [Related feature] - [Advanced tutorial] ```` --- ## Success Stories & Case Studies ### Core Philosophy Combine human narratives with quantifiable business impact following: Challenge → Solution → Results → Vision. ### Key Principles #### 1. Impact-First Opening ```markdown Air India has handled nearly 4 million customer queries with 97% full automation, saving millions of dollars in customer support costs. ```` #### 2. Three-Part Structure - **Challenge (20%)**: Context, pain points, stakes - **Solution (30%)**: Decision process, implementation, tech stack - **Results (50%)**: Metrics, benefits, transformation #### 3. Metrics Framework **Primary Metrics (Choose 2-3)** - Efficiency: "90% reduction in processing time" - Scale: "Handling 20,000+ queries daily" - Cost: "50% reduction in operational costs" - Automation: "97% of queries fully automated" **Visual Display:** ``` [97%] [4M] [$Millions] Queries Automated Total Queries Handled In Cost Savings ``` #### 4. Executive Quote Formula ```markdown "[Strategic vision]. [Specific achievement]. [Future aspiration]." — Name, Title, Company ``` #### 5. Industry Customization - **B2B**: Focus on ROI, efficiency, scale - **B2C**: Emphasize user experience, engagement - **Healthcare**: Patient outcomes, compliance - **Financial**: Security, accuracy, speed ### Example Template ```markdown # [Company] Achieves [Key Metric] with [Solution] ## The Challenge [Company background and specific problems faced] ## The Solution [Why they chose this approach and implementation details] ## The Results ### By the Numbers - [Metric 1]: [Specific achievement] - [Metric 2]: [Specific achievement] - [Metric 3]: [Specific achievement] ### Business Impact [Qualitative benefits and transformation story] > "[Executive quote validating the transformation]" — Executive Name, Title ## What's Next [Future vision and expansion plans] ## Get Started [Call to action for readers] ``` --- ## Quick Reference Guide ### When to Use Each Style | Situation | Style Choice | Key Focus | | ---------------------------- | -------------- | ------------------------- | | Sharing engineering insights | Cursor Blog | Problem-solving narrative | | Enabling feature usage | Anthropic Docs | Task completion | | Showcasing achievements | Success Story | Business impact | | Teaching concepts | Cursor Blog | Learning journey | | API/tool reference | Anthropic Docs | Implementation steps | | Building credibility | Success Story | Measurable results | ### Tone Quick Reference #### Engineering Blog (Cursor) - Conversational but technical - Honest about failures - Exploratory and curious - "We/I" perspective #### Documentation (Anthropic) - Direct and confident - Task-focused - "You" perspective - Zero ambiguity #### Success Stories - Celebratory but credible - Metric-driven - Third-person perspective - Future-oriented --- ## Style Comparison Matrix | Element | Engineering Blog | Documentation | Success Story | | ------------- | --------------------------- | ------------------ | ----------------- | | **Opening** | Problem/failure scenario | "When to use" | Impact metrics | | **Structure** | Problem→Solution narrative | Task→Steps→Tips | Challenge→Results | | **Evidence** | Code examples, architecture | Commands, examples | Business metrics | | **Length** | 2-19 min reads | Scannable sections | 250-1500 words | | **Visuals** | Diagrams, code blocks | Tables, warnings | Metric displays | | **Voice** | First person plural | Second person | Third person | | **Tone** | Exploratory | Instructional | Inspirational | | **Ending** | Open questions | Next steps | Vision/CTA | ### Universal Best Practices 1. **Clarity First**: Complex ideas, simple language 2. **Show, Don't Tell**: Examples before explanations 3. **Progressive Depth**: Simple → Complex 4. **Visual Hierarchy**: Headers, bullets, formatting 5. **Actionable Content**: Reader can do something after reading ### What to Avoid (All Styles) - ❌ Unexplained jargon - ❌ Vague promises ("revolutionary", "game-changing") - ❌ Buried important information - ❌ Fake or unverifiable metrics - ❌ Overly long introductions - ❌ Passive voice in instructions - ❌ Marketing fluff in technical content --- ## MDX Writing Guidelines ### What is MDX? MDX allows you to use JSX in your markdown content. This enables interactive components, but requires careful syntax handling. ### MDX Syntax Rules #### 1. Self-Closing HTML Tags All void HTML elements must be self-closing: **❌ Incorrect:** ```markdown Line break here
Horizontal rule

Image

``` **✅ Correct:** ```markdown Line break here
Horizontal rule

Image

``` #### 2. Escaping Special Characters MDX uses curly braces for expressions. Escape them in regular text: **❌ Incorrect:** ```markdown The object format is {key: value} ``` **✅ Correct:** ```markdown The object format is \{key: value\} ``` #### 3. HTML Attributes Use camelCase for attributes: **❌ Incorrect:** ```html

``` **✅ Correct:** ```jsx

``` #### 4. Tables with HTML When using HTML in tables, ensure proper escaping: **❌ Incorrect:** ```markdown | Option | Description | | ------ | --------------------------- | | A | First option
Second line | ``` **✅ Correct:** ```markdown | Option | Description | | ------ | ---------------------------- | | A | First option
Second line | ``` ### Common MDX Pitfalls 1. **Unclosed Tags**: All HTML tags must be properly closed 2. **Component Usage**: Import components at the top if using custom React components 3. **Inline Styles**: Use style objects, not strings ```jsx // ❌ Wrong

// ✅ Correct

``` ### Blog Post Frontmatter Always include complete frontmatter: ```yaml --- title: 'Your Post Title' excerpt: 'A brief description of your post' date: '2024-06-06' author: 'Author Name' category: 'category-slug' tags: ['tag1', 'tag2', 'tag3'] --- ``` ### Categories Use one of these category slugs: - `welcome` - `user-guides` - `teaching-cs-ai` - `student-stories` - `parents-corner` - `schools` - `resources` --- ## Implementation Checklist Before publishing any piece, verify: ### For Engineering Blogs - [ ] Opens with concrete problem - [ ] Includes failed attempts - [ ] Shows real code/architecture - [ ] Honest about limitations - [ ] Ends with open questions - [ ] All HTML tags are self-closing - [ ] Special characters are escaped ### For Documentation - [ ] Every section has "When to use" - [ ] Examples come before explanations - [ ] Includes practical tips - [ ] Progressive disclosure applied - [ ] Clear next steps provided - [ ] MDX syntax is valid ### For Success Stories - [ ] Leads with biggest impact - [ ] 2-3 primary metrics highlighted - [ ] Executive quote included - [ ] Visual metric displays - [ ] Clear vision for future - [ ] Tables use proper HTML escaping --- ## Final Words Each writing style serves a specific purpose in the technical content ecosystem: - **Engineering Blogs** inspire and educate through shared experiences - **Documentation** enables successful implementation - **Success Stories** prove value and inspire action Master all three styles to create a complete content strategy that engages engineers, enables users, and excites stakeholders. Remember: The best technical writing makes complex things feel simple while respecting the reader's intelligence.

Blog

Blog

Browse by Category

Browse by Category