Article Style Guide

Essential rules and guidelines for creating articles that respect our readers' intelligence

By Jay Capers7/29/20256 min read
writingstyle guidedocumentationbest practices

Article Style Guide: Writing Clear, Useful Content

This style guide helps maintain consistency and quality across all articles. Follow these rules to create content that genuinely helps readers understand complex topics.

Specific Rules (Must Follow)

1. Banned Clichés and Phrases

NEVER use these phrases:

These phrases are overused SEO filler that immediately signal low-quality content. Write like a real person explaining something to a colleague, not a corporate marketing department.

2. Code Examples Must Be Runnable

When including code, ensure it's complete and functional:

Bad:

// Process data somehow
processData(data)

Good:

const processData = (data) => {
  return data
    .filter(item => item.active)
    .map(item => ({
      id: item.id,
      name: item.name.trim(),
      timestamp: Date.now()
    }));
};

3. Headers Should Be Scannable

Use headers that clearly indicate what information follows. Avoid clever wordplay or vague descriptions.

Bad: "The Journey Begins" Good: "Installation and Setup"

4. Optimal Article Length: 2,000-4,000 Words

Search engines favor comprehensive content that thoroughly covers a topic. Aim for:

This length allows you to rank for multiple related keywords while providing genuine value.

5. Use Numbers in Titles

Articles with numbered lists consistently perform better:

Numbers create clear expectations and make content feel digestible.

6. Write Like a Human, Not a Corporation

Your writing should sound like one developer explaining something to another, not a press release.

Corporate/Soulless:

Human/Authentic:

Remember: If you wouldn't say it in a conversation with a colleague, don't write it in an article.

SEO-Focused Writing Strategies

1. Hook With Pain Points, Not Products

Start articles by acknowledging the reader's current struggles:

Bad Opening: "Our background agent platform offers cutting-edge automation capabilities..."

Good Opening: "If you're manually checking server logs every morning, copying data between systems, or running the same scripts repeatedly, you're wasting hours each week on tasks a simple agent could handle."

2. The 80/20 Content Rule

Structure articles with:

This builds trust and provides value even to readers who don't become customers.

3. Target High-Intent Keywords

Focus on searches that indicate someone has a specific problem:

4. Include Comparison Content

Create articles comparing approaches:

General Guidelines

1. Concrete Examples Over Abstract Concepts

When explaining features or use cases, provide specific, real-world examples that readers can immediately understand and relate to their work.

Too Abstract: "Workflow Automation and Integration - Background agents can transform how businesses operate by automating complex workflows."

Concrete and Specific: "Slack-to-Jira Integration - A background agent monitors your team's Slack channel for bug reports. When someone types 'BUG:' followed by a description, the agent automatically creates a Jira ticket with the message content, assigns it to the on-call developer, and replies in Slack with the ticket number."

2. Show Impact with Numbers

Whenever possible, quantify the benefits or impact:

3. Write for Skimmers

Most readers scan before reading. Structure content for easy scanning:

4. Technical Accuracy Matters

5. Voice and Tone

6. SEO-Optimized Article Structure

  1. Hook Opening (50-100 words)

    • Start with a relatable problem or pain point
    • Promise specific solutions
    • Avoid long philosophical introductions

  2. Table of Contents (for articles over 2,000 words)

    • Use anchor links to sections
    • Helps with featured snippets in Google

  3. What/Why Section (200-300 words)

    • Define the core concept clearly
    • Explain why readers should care

  4. Main Content (1,500-3,000 words)

    • Break into 5-10 digestible sections
    • Each section should answer a specific question
    • Use numbered or bulleted lists liberally

  5. Implementation Examples (500-1,000 words)

    • Provide 3-5 concrete, implementable examples
    • Include code snippets, commands, or screenshots
    • Show time/resource requirements

  6. Conclusion & CTA (100-200 words)

    • Summarize key takeaways
    • Provide clear next steps
    • Subtle product mention if relevant

7. Avoid Fluff

Every sentence should add value. Cut:

8. Use Active Voice

Passive: "The configuration file must be edited by the user" Active: "Edit the configuration file"

9. Include Failure Cases

Don't just show the happy path. Include:

10. Build Authority with External References

Strengthen your content by:

Example: "As Martin Fowler notes in his essay on Continuous Integration, 'Automate everything that can be automated.'"

11. Format for Featured Snippets

Structure content to win Google's featured snippets:

12. Internal Linking Strategy

Examples of Good Writing

Good SEO-Optimized Title

"15 Python Background Agents That Eliminate Manual DevOps Tasks"

Good Pain Point Opening

"If you're still SSH-ing into servers to check disk space, manually rotating logs, or copy-pasting data between systems, you're not alone. A recent DevOps survey found that engineers waste 8 hours per week on repetitive tasks. Here's how to reclaim that time with background agents."

Good Concrete Example

"Kubernetes Pod Monitor: This Go agent polls your cluster every 30 seconds, checking for pods in CrashLoopBackOff state. When detected, it:

  1. Captures the last 50 lines of logs
  2. Creates a GitHub issue with the error details
  3. Notifies the on-call engineer via PagerDuty
  4. Attempts one automatic restart

Setup takes 15 minutes. Resource usage: 25MB RAM, 0.1% CPU on a typical cluster."

Good Authority Reference

"Following the principles from Google's Site Reliability Engineering book, this agent implements exponential backoff with jitter, ensuring it won't overwhelm struggling services with retry attempts."

Good CTA Section

"Start automating your repetitive tasks today. Pick one task from this article and implement it this week. For teams ready to scale their automation, [Product Name] provides a managed platform with pre-built agents, monitoring, and enterprise support."

Remember: SEO success comes from genuinely helping readers solve problems. Search engines reward content that satisfies user intent with comprehensive, actionable information.

Technical Details

YAML Frontmatter Requirements

All articles use YAML frontmatter for metadata. To avoid parsing errors:

1. Always quote strings containing colons

Colons (:) in YAML indicate key-value pairs. If your title or description contains a colon, you must quote the entire string.

Bad:

title: How to Monitor AI: 5 Essential Tips
description: Learn AI monitoring: tools, techniques, and best practices

Good:

title: "How to Monitor AI: 5 Essential Tips"
description: "Learn AI monitoring: tools, techniques, and best practices"

2. Quote strings with special characters

These characters require quoting: :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `

Examples:

title: "10% Better Performance with These Tricks"        # Contains %
title: "AI vs ML: What's the Difference?"               # Contains :
title: "The #1 Monitoring Tool for AI Agents"           # Contains #
description: "Track costs & optimize performance"        # Contains &

3. Use consistent quoting style

Prefer double quotes for consistency across all frontmatter fields:

---
title: "Your Article Title Here"
slug: "your-article-slug"
description: "Your meta description here"
date: "2025-08-01"
published: true
tags: ['tag1', 'tag2', 'tag3']
author: "Author Name"
---

4. Validate YAML before committing

Test your frontmatter with a YAML validator to catch errors early:

# Quick validation using Python
python -c "import yaml; yaml.safe_load(open('your-article.md').read().split('---')[1])"

5. Common YAML pitfalls to avoid

By following these guidelines, you'll avoid deployment errors and ensure your articles build successfully.