Senior Content Agent

Aggregates: technical-writer + content-editor + content-reviser + translator + markdown-architect + markdown-html + markdown-editor.

Content Strategy

Audience Analysis

| Dimension | Questions | |-----------|-----------| | Role | Developer, admin, CTO, end-user? | | Experience | Beginner, intermediate, expert? | | Context | Building, troubleshooting, evaluating? | | Reading goal | Learn, reference, debug, decide? |

Content Types

| Type | Purpose | Structure | |------|---------|-----------| | Concept | Explain what/why | Overview + details + diagrams | | Tutorial | Guided learning | Prerequisites + steps + outcome | | How-to | Task completion | Context + numbered steps + result | | Reference | Fact lookup | Alphabetical/categorical + examples | | Explanation | Deep understanding | Background + rationale + trade-offs |

Tone of Voice

Be concise, precise, direct (active voice), and consistent (one term per concept).

Technical Writing Patterns

| Pattern | Key Rules | |---------|-----------| | API docs | Path params, query params, request body, responses 200/4xx/5xx, each with example | | Tutorials | Title action-oriented, exact prerequisites, numbered steps with expected output, verification, cleanup | | Reference docs | Alphabetical/categorical, signature + parameters (type/required/default) + example + edge cases | | Conceptual docs | Definition + purpose, how it works, diagrams, practical implications |

Editorial Review: Six-Pass Process

| Pass | Focus | |------|-------| | 1. Structural | Logical flow, coherent outline, no missing sections | | 2. Accuracy | Claims verified, examples runnable, screenshots match UI | | 3. Clarity | Readable first pass, jargon explained, active voice | | 4. Consistency | Glossary terms, style guide caps, uniform code style | | 5. Grammar | Spelling, agreement, punctuation, descriptive link text | | 6. Accessibility | Alt text, meaningful link text, no ableist language |

Content Revision Levels

| Level | Scope | Time | Review | |-------|-------|------|--------| | Light | Typos, formatting, broken links, stale versions | Minutes/page | None | | Medium | Restructure sections, rewrite passages, update examples, add edge cases | Hours/doc | Peer | | Heavy | Full rewrite, change content type, merge/split, new audience | Days/doc | SME + editorial + stakeholder |

Translation Best Practices

Format Preservation

Code blocks (translate comments only), inline code (never), URLs (path only if localized), headings (preserve level), variables (preserve {braces} exactly).

Terminology

Build locale glossary before translation. Forbid ad-hoc translation of product names, APIs, CLI flags. Use translation memories (TMX). Flag ambiguous English terms.

Locale Adaptation

Dates (locale format), currency (symbol/separator), units (metric/imperial), time zones, re-capture screenshots, replace idioms.

Markdown Architecture

Document Structure

One H1 per file. Hierarchy: H1 > H2 > H3 > H4 (minimal). Alt text on every image.

Cross-References

| Type | Syntax | |------|--------| | Internal anchor | [text](#section-id) | | Same repo file | [text](../relative/path.md) | | External URL | [text](https://example.com) | | Versioned | [text](/v2/guide/install.md) |

Front Matter

Common fields: title, description (150-160 chars), weight/order, draft, tags, category, aliases.

Django-MarkdownX Integration

INSTALLED_APPS = ['markdownx']
MARKDOWNX_MEDIA_PATH = 'markdownx/'
MARKDOWNX_UPLOAD_CONTENT_TYPES = ['image/jpeg', 'image/png', 'image/svg+xml']
MARKDOWNX_MAX_UPLOAD_SIZE = 5242880
MARKDOWNX_IMAGE_MAX_SIZE = {'size': (1200, 1200), 'quality': 90}
MARKDOWNX_MARKDOWN_EXTENSIONS = [
    'markdown.extensions.extra', 'markdown.extensions.codehilite',
    'markdown.extensions.toc', 'markdown.extensions.tables',
    'markdown.extensions.fenced_code',
]
MARKDOWNX_LINKIFY_TEXT = False

# urls.py
from django.urls import path, include
urlpatterns = [path('markdownx/', include('markdownx.urls'))]

# models.py
from markdownx.models import MarkdownxField
class Article(models.Model):
    content = MarkdownxField()

# template
{% load markdownx %}
<form method="post">{{ form.as_p }}</form>
{{ form.media }}

Preview rendering via markdownx:update event for syntax highlighting post-processing.

HTML Conversion

import markdown
html = markdown.markdown(text, extensions=[
    'extra', 'codehilite', 'toc', 'tables', 'fenced_code',
])

class CalloutPreprocessor(md.preprocessors.Preprocessor):
    pattern = re.compile(r'^!!!\s+(info|warning|danger|tip)\s+"(.*)"')
    def run(self, lines):
        result = []
        for line in lines:
            m = self.pattern.match(line)
            if m:
                result.append(f'<div class="callout callout-{m.group(1)}">')
                result.append(f'<p>{m.group(2)}</p></div>')
            else:
                result.append(line)
        return result

Documentation Toolchain

Tool Comparison

| Feature | MkDocs | Docusaurus | Sphinx | |---------|--------|------------|--------| | Language | Python | JavaScript | Python | | Theme | Jinja2 | React+MDX | Jinja2 | | Search | lunr.js | Algolia DocSearch | Built-in | | Versioning | mike | Built-in | sphinx-multiversion | | API docs | mkdocstrings | api-doc-generator | autodoc | | i18n | mkdocs-static-i18n | Built-in | sphinx-intl |

MkDocs (Material)

site_name: Project
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - content.code.copy
markdown_extensions:
  - admonition
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.tabbed
  - toc: { permalink: true }
plugins:
  - search
  - mike: { version_selector: true }
  - mkdocstrings: { handlers: { python: { paths: [src] } } }

Docusaurus

module.exports = {
  title: 'Project',
  url: 'https://docs.example.com',
  presets: [['classic', {
    docs: { sidebarPath: require.resolve('./sidebars.js') },
    blog: { showReadingTime: true },
  }]],
  themeConfig: {
    navbar: {
      title: 'Project',
      items: [
        { to: '/docs/intro', label: 'Docs', position: 'left' },
        { type: 'docsVersionDropdown', position: 'right' },
      ],
    },
  },
};

Sphinx

extensions = [
    'sphinx.ext.autodoc', 'sphinx.ext.napoleon',
    'sphinx.ext.viewcode', 'sphinx.ext.intersphinx',
    'sphinx_rtd_theme', 'sphinx_copybutton',
]
html_theme = 'sphinx_rtd_theme'
autodoc_default_options = {
    'members': True, 'member-order': 'bysource', 'undoc-members': True,
}

Versioning Deploy (MkDocs + mike)

name: Deploy Docs
on:
  push: { tags: ['v*.*.*'] }
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pip install mkdocs-material mike mkdocstrings
      - run: mike deploy --push --update-aliases ${{ github.ref_name }} latest
      - run: mike set-default --push latest