Content Strategy for Documentation: Audience Analysis, Audits, and Editorial Calendars

# persona-beginner-developer.yml
name: Alex
role: Junior Developer
experience: 1-2 years
goals:
  - Integrate the API quickly
  - Understand basic concepts
  - Get a working prototype
pain_points:
  - Overwhelmed by documentation
  - Doesn't know terminology
  - Needs step-by-step guidance
preferred_content:
  - Tutorials with code examples
  - Quickstart guides
  - Video walkthroughs

# persona-senior-engineer.yml
name: Jordan
role: Senior Platform Engineer
experience: 8+ years
goals:
  - Evaluate API for architecture fit
  - Understand performance characteristics
  - Plan migration strategy
pain_points:
  - Too much beginner content
  - Hard to find reference docs
  - Missing edge case documentation
preferred_content:
  - API reference documentation
  - Performance benchmarks
  - Architecture guides

# content_inventory.py
import os
import yaml
from datetime import datetime

class ContentInventory:
    def __init__(self, content_dir):
        self.content_dir = content_dir
        self.pages = []

    def scan(self):
        for root, dirs, files in os.walk(self.content_dir):
            for file in files:
                if file.endswith('.md'):
                    path = os.path.join(root, file)
                    with open(path) as f:
                        content = f.read()
                        if content.startswith('---'):
                            _, fm, body = content.split('---', 2)
                            meta = yaml.safe_load(fm)
                            self.pages.append({
                                'path': path,
                                'title': meta.get('title', 'Untitled'),
                                'weight': meta.get('weight', 99),
                                'description': meta.get('description', ''),
                                'lastmod': meta.get('lastmod', 'Unknown'),
                                'word_count': len(body.split()),
                                'has_code': '```' in body,
                                'has_faq': '{{< faq >}}' in body,
                                'has_images': '![' in body or '<img' in body,
                            })

    def quality_report(self):
        total = len(self.pages)
        stale = [p for p in self.pages if p['lastmod'] < '2025-01-01']
        no_desc = [p for p in self.pages if not p['description']]
        no_code = [p for p in self.pages if not p['has_code']]
        short = [p for p in self.pages if p['word_count'] < 300]

        print(f"Total pages: {total}")
        print(f"Stale (not updated in 6+ months): {len(stale)}")
        print(f"Missing description: {len(no_desc)}")
        print(f"No code examples: {len(no_code)}")
        print(f"Short (< 300 words): {len(short)}")

        # Category breakdown
        from collections import Counter
        categories = Counter()
        for p in self.pages:
            category = p['path'].split('/')[-2]  # Parent directory
            categories[category] += 1
        print("\nPages by category:")
        for cat, count in categories.most_common():
            print(f"  {cat}: {count}")

inventory = ContentInventory('content/')
inventory.scan()
inventory.quality_report()

# Editorial Calendar — Q3 2026

## July
Week 1: [Write] Getting Started Guide (update)
Week 2: [Write] API Authentication Tutorial (new)
Week 3: [Review] Troubleshooting Guide (stale)
Week 4: [Publish] API Authentication Tutorial

## August
Week 1: [Write] Performance Optimization Guide (new)
Week 2: [Write] Configuration Reference (update)
Week 3: [Review] All tutorials for freshness
Week 4: [Publish] Performance Optimization Guide

## September
Week 1: [Research] Content audit and gap analysis
Week 2: [Plan] Q4 content priorities
Week 3: [Write] Video: Quick Start Walkthrough
Week 4: [Publish] Video + Recap blog post

## Content Request Template

Title: [Working title]
Type: [Tutorial | Reference | Guide | FAQ | Video]
Audience: [Beginner | Intermediate | Advanced]
Priority: [P0 | P1 | P2 | P3]
Status: [Planned | Writing | Review | Published | Archived]
Target date: [YYYY-MM-DD]
Author: [Name]
Reviewer: [Name]

Description:
[2-3 sentences describing what this content will cover]

Success metrics:
- Page views (first 30 days): [target]
- Time on page: [target]
- Support ticket reduction: [target]

# Simple content analytics tracker
class ContentAnalytics:
    def __init__(self):
        self.pages = {}

    def record_view(self, path, duration_seconds):
        if path not in self.pages:
            self.pages[path] = {"views": 0, "total_duration": 0}
        self.pages[path]["views"] += 1
        self.pages[path]["total_duration"] += duration_seconds

    def report(self):
        for path, data in sorted(
            self.pages.items(),
            key=lambda x: x[1]["views"],
            reverse=True
        ):
            avg_duration = data["total_duration"] / data["views"]
            print(f"{path}: {data['views']} views, {avg_duration:.0f}s avg")

analytics = ContentAnalytics()
analytics.record_view("/getting-started/", 245)
analytics.record_view("/api-reference/", 120)
analytics.record_view("/getting-started/", 180)
analytics.report()