WordPress Documentation Review

This skill provides systematic review of WordPress documentation against the official WordPress Documentation Style Guide.

When to Use This Skill

Use this skill when:

• •Reviewing WordPress documentation before publication
• •Auditing existing documentation for style guide compliance
• •Providing feedback on documentation pull requests
• •Ensuring documentation meets WordPress standards

Review Process

Step 1: Understand the Documentation Type

Identify the documentation type to apply appropriate standards:

• •End-user documentation: Focus on clarity, accessibility, and conversational tone
• •Developer documentation: Allow technical precision while maintaining clarity
• •Code reference: Emphasize accuracy and code standards compliance
• •Tutorial/guide: Check procedural clarity and step-by-step flow

Step 2: Systematic Review

Review documentation in this order for comprehensive coverage:

A. General Guidelines

Document Structure

• • Follows defined structure with clear hierarchy
• • Uses proper heading levels (H1 → H6, no skipping)
• • Breaks text into digestible paragraphs (not walls of text)
• • Includes introductory context before diving into details

Voice and Tone

• • Conversational yet professional tone
• • Avoids "we" statements (e.g., "we recommend" → "you can")
• • Uses second person ("you") to address readers directly
• • Avoids colloquialisms, slang, and cultural references
• • No excessive claims about WordPress products/features
• • No predictions about future features

Accessibility

• • Alt text provided for all images (50 char limit)
• • No color-only information conveyance
• • Clear link text (not "click here")
• • Proper table structure (no complex rowspan/colspan)
• • No flickering/flashing content

Inclusivity

• • Gender-neutral language throughout
• • Uses "they/their/them" for singular pronouns
• • Avoids ableist language
• • No cultural/religious bias
• • Diverse examples (names, locations, professions)
• • Preferred terminology:
  • •"allowlist" (not "whitelist")
  • •"blocklist" (not "blacklist")
  • •"main" (not "master" branch)
  • •"primary/subordinate" (not "master/slave")

Global Audience

• • American English spelling (color, optimize)
• • Date format: Month DD, YYYY (e.g., October 28, 2025)
• • Spells out numbers one through nine
• • Times in UTC when relevant
• • No idioms or culturally-specific references
• • Simple sentence structure for translation

B. Language and Grammar

Voice and Tense

• • Active voice (not passive)
• • Present tense (not future)
• • Second person perspective

Capitalization

• • Sentence case for headings
• • UI elements match exact capitalization from interface
• • Proper nouns capitalized appropriately

Articles and Clarity

• • Articles (a, an, the) included where appropriate
• • Contractions used appropriately
• • Conditional clauses before instructions
• • Clear pronoun antecedents

C. Developer Content

Code in Text

• • Monospace font for: filenames, paths, commands, functions, variables, UI elements with user input
• • Proper formatting for method names with empty parentheses: delete()
• • Keywords not used as verbs or pluralized

Code Examples

• • Proper indentation (spaces, not tabs)
• • Lines wrapped at 80 characters
• • Introductory sentence before code blocks
• • Follows WordPress Coding Standards
• • Syntax highlighting where applicable

Placeholders

• • Enclosed in <var> tags in HTML or backticks+asterisks in Markdown
• • Uppercase with underscores: *POST_ID* or <var>POST_ID</var>
• • No possessive pronouns (MY_, YOUR_)
• • Description list provided for multiple placeholders

Command-line Syntax

• • Dollar sign ($) prompt for commands
• • Optional arguments in square brackets: [--force]
• • Mutually exclusive arguments in angle brackets: <plugin|zip|url>
• • Multiple values indicated with ellipsis: ...
• • Proper line continuation characters (\ for Linux, ^ for Windows)

UI Elements

• • Names in bold: Settings
• • Task-focused instructions (not click-focused)
• • Proper element terminology (button, menu, field)

D. Punctuation

• • Serial (Oxford) commas in lists
• • One space after periods
• • Em dashes (—) for breaks, en dashes (–) for ranges
• • Straight quotes (not curly quotes)
• • Minimal exclamation points
• • Minimal parentheses

E. Formatting

Links

• • Descriptive link text (not "click here" or bare URLs)
• • Cross-references to related content
• • External links to authoritative sources only

Lists

• • Numbered lists for sequential steps
• • Bulleted lists for non-sequential items
• • Parallel structure in list items
• • Sentence case for list items

Media

• • Images in SVG or PNG format
• • Alt text provided (< 50 characters)
• • Screenshots at appropriate resolution
• • Focused on relevant content

Tables

• • Simple structure (avoid rowspan/colspan)
• • Headers properly marked
• • Mobile-friendly layout

Step 3: Provide Structured Feedback

Organize feedback by priority:

Critical Issues (Must fix before publication)

• •Accessibility violations
• •Incorrect technical information
• •Code that doesn't follow WordPress standards
• •Offensive or non-inclusive language

Important Issues (Should fix)

• •Voice/tone inconsistencies
• •Unclear instructions
• •Missing alt text or descriptions
• •Formatting inconsistencies

Suggestions (Nice to have)

• •Style improvements
• •Additional examples
• •Enhanced clarity

Step 4: Generate Review Output

Format the review as:

## WordPress Documentation Review

### Summary
[Brief overview of documentation quality and main findings]

### Critical Issues
1. [Issue with specific location and fix]
2. [Issue with specific location and fix]

### Important Issues
1. [Issue with specific location and fix]
2. [Issue with specific location and fix]

### Suggestions
1. [Improvement with rationale]
2. [Improvement with rationale]

### Positive Highlights
- [What the documentation does well]
- [Effective techniques used]

### Overall Assessment
[Overall rating and readiness for publication]

Reference Materials

For detailed guidance on specific topics, consult:

• •references/developer-content.md - Code examples, placeholders, command-line syntax, UI elements
• •references/style-guidelines.md - Complete style, voice, and tone guidelines with examples

Key Terminology Reference

Best Practices

1. •Be specific: Point to exact locations with line numbers or section headings
2. •Provide examples: Show correct and incorrect versions side-by-side
3. •Explain why: Connect feedback to style guide principles
4. •Balance criticism: Acknowledge what works well
5. •Prioritize: Focus on issues that impact understanding or accessibility first