Add documentation-docusaurus agent skill

Packages generic-documentation-v1 as documentation-docusaurus: Diataxis quadrants, structure and voice rules, and four references for patterns, writing, config, and deployment. Content preserved from the source; renames the skill, strengthens the description for triggering, and converts the reference list into a routing table stating when to load each file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-30 22:58:08 +03:00
parent ed7c7f0d95
commit a596731f67
6 changed files with 1189 additions and 1 deletions
@@ -1 +1,53 @@
 # documentation-docusaurus
 Agent Skill for building documentation sites with **Docusaurus**, structured on the
 [Diátaxis](https://diataxis.fr/) framework — tutorials, how-to guides, reference, and
 explanation kept strictly apart.
 Opinionated by design. It takes positions on structure, voice, and configuration rather than
 listing options, and it asks who the reader is and what they should be able to *do* before
 writing anything.
 ## Layout
 ```text
 documentation-docusaurus/
 ├── SKILL.md                          # Entry point — Diátaxis quadrants, structure, voice rules
 └── references/
    ├── diataxis-patterns.md          # Template per quadrant, decision tree, cross-linking
    ├── writing-guide.md              # Voice, words to cut, inclusive language, checklist
    ├── config-reference.md           # docusaurus.config.ts — what matters, what to leave alone
    └── deployment.md                 # Vercel, Netlify, GitHub Pages, Cloudflare, debugging
 ```
 ## The core idea
 | Type | Purpose | Question it answers |
 |---|---|---|
 | **Tutorial** | Learning | "Can you teach me to…?" |
 | **How-to** | Doing | "How do I…?" |
 | **Reference** | Information | "What is the API for…?" |
 | **Explanation** | Understanding | "Why does…?" |
 Don't mix them. A tutorial that turns into reference halfway through loses both audiences.
 The docs tree follows the reader's journey — learn, do, understand, look up:
 ```text
 docs/
 ├── getting-started/     # Tutorials
 ├── guides/              # How-tos
 ├── concepts/            # Explanation
 ├── reference/           # Reference
 └── resources/           # Links, community, changelog
 ```
 ## Deploy
 ```bash
 cd ../skill-manager/scripts
 task deploy -- --skill-dir="$(cd ../../documentation-docusaurus && pwd)"
 ```
 Built with the `skill-manager` skill, following the
 [agentskills.io specification](https://agentskills.io/specification).
@@ -0,0 +1,185 @@
 ---
 name: documentation-docusaurus
 description: >
  Opinionated guidance for building and restructuring Docusaurus documentation sites on the
  Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, and
  refusing to mix them on one page. Use when creating a new docs site or page, reorganising an
  existing one, deciding which quadrant a page belongs to, writing frontmatter, sidebars, or
  admonitions, editing docusaurus.config.ts, applying voice and inclusive-language standards,
  or setting up deployment to Vercel, Netlify, GitHub Pages, or Cloudflare Pages. Triggers on
  docs/, blog/, docusaurus.config, sidebars.ts, .mdx files, or any request to write, improve,
  or restructure documentation — even when the user only says "write docs", "document this",
  or "the docs are a mess". Asks who the reader is and what they should be able to DO before
  writing, because the answer decides the structure.
 license: MIT
 metadata:
  author: workspace-skills-code-agent
  version: "1.0"
  spec: agentskills.io/specification
  framework: Diátaxis
 compatibility: Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments
 ---
 # Docusaurus Documentation Skill
 *Opinionated guidance for building documentation people actually read.*
 ## My Philosophy
 Documentation isn't about documenting—it's about **enabling**. Every page should answer one question: "What can the reader DO after reading this?"
 I follow the **Diátaxis framework**. Before writing anything, identify which quadrant you're in:
 | Type | Purpose | User State | Question Answered |
 |------|---------|------------|-------------------|
 | **Tutorial** | Learning | "I'm new, teach me" | "Can you teach me to...?" |
 | **How-to** | Doing | "I need to accomplish X" | "How do I...?" |
 | **Reference** | Information | "I need to look up Y" | "What is the API for...?" |
 | **Explanation** | Understanding | "I want to understand why" | "Why does...?" |
 **Don't mix them.** A tutorial that becomes reference midway loses both audiences.
 ## Before You Write: Questions I'll Ask
 When you ask me to create documentation, I need to understand:
 1. **Who is reading this?** (New user? Developer? API consumer? Decision maker?)
 2. **What should they be able to DO after?** (Not "know"—DO)
 3. **Which Diátaxis quadrant?** (Tutorial/How-to/Reference/Explanation)
 4. **What do they already know?** (Prerequisites matter)
 If you haven't thought through these, I'll ask. Good docs require clear thinking first.
 ## Structure: My Strong Opinions
 ### Sidebar Organization
 ```
 docs/
 ├── getting-started/          # Tutorials: learning journeys
 │   ├── _category_.json       # collapsed: false
 │   └── ...
 ├── guides/                   # How-tos: task completion
 ├── concepts/                 # Explanation: understanding
 ├── reference/                # Reference: lookup
 │   ├── api/
 │   └── configuration/
 └── resources/                # Links, community, changelog
 ```
 **Why this order?** It matches the reader's journey: Learn → Do → Understand → Look up.
 ### Frontmatter: Non-Negotiables
 Every doc needs these. No exceptions:
 ```yaml
 ---
 title: "Action-Oriented Title"        # What they'll DO, not what it IS
 description: "One sentence outcome"   # Appears in search, make it count
 ---
 ```
 Skip `sidebar_position` unless order matters semantically. Let alphabetical work.
 ### Writing Rules I Enforce
 **Tutorials:**
 - Start with what they'll BUILD, not what they'll LEARN
 - One path only—no "alternatively" or "you could also"
 - Every step produces visible output
 - Link to explanation, don't embed it
 **How-to Guides:**
 - Title format: "How to [verb] [thing]"
 - Assume competence—skip basics
 - Start with the goal, not the tool
 - Include "What you'll need" upfront
 **Reference:**
 - Mirror the code structure exactly
 - Tables over prose for specs
 - Examples for every endpoint/function
 - No tutorials hiding in reference
 **Explanation:**
 - Answer "why" not "how"
 - Connect to bigger picture
 - Acknowledge trade-offs and alternatives
 - Can be opinionated—this is where you explain decisions
 ## Inclusive Language: Required
 Use these replacements. This isn't optional:
 | Avoid | Use Instead |
 |-------|-------------|
 | whitelist/blacklist | allowlist/blocklist |
 | master/slave | primary/replica, main/secondary |
 | sanity check | confidence check, validation |
 | dummy value | placeholder, sample |
 | guys | folks, everyone, team |
 | simple/easy | (just remove it) |
 **Why "simple" is banned:** What's simple to you isn't simple to the reader. Saying "simply run X" makes struggling readers feel dumb.
 **Pronouns:** Use "you" for the reader. Use "they" for hypothetical users. Avoid "we" unless it's genuinely collaborative.
 ## Dynamic Documentation Patterns
 ### Interactive Elements (Use Sparingly)
 Tabs for platform differences:
 ```mdx
 <Tabs groupId="os">
  <TabItem value="mac" label="macOS" default>
 ```
 Details for optional deep-dives:
 ```mdx
 <details>
 <summary>Why does this matter?</summary>
 ...explanation that most readers can skip...
 </details>
 ```
 **Don't use tabs for:** Code language alternatives (pick one and show it well), or "beginner vs advanced" (separate pages instead).
 ### Admonitions: The Hierarchy
 ```
 :::tip        → "This will make your life easier"
 :::note       → "Relevant context you might miss"
 :::warning   → "This could cause problems"
 :::danger    → "This WILL break things if ignored"
 ```
 **One admonition per section max.** If everything is highlighted, nothing is.
 ## What I Won't Do
 - Create docs without understanding the audience
 - Mix documentation types in one page
 - Add "simple" or "easy" to instructions
 - Generate walls of code without context
 - Skip frontmatter description fields
 - Create sidebars deeper than 3 levels
 ## Reference Files
 Load the one that matches the task. Don't read all four.
 | You're about to | Read |
 |---|---|
 | Write a page, or decide which quadrant it belongs in | [references/diataxis-patterns.md](references/diataxis-patterns.md) — copy-ready template per quadrant, the decision tree, and how to link between them |
 | Write or edit prose, headings, lists, or code examples | [references/writing-guide.md](references/writing-guide.md) — voice, words to cut, inclusive language, pre-publish checklist |
 | Touch `docusaurus.config.ts` | [references/config-reference.md](references/config-reference.md) — the options that matter, sensible defaults, config anti-patterns |
 | Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
 ## Getting Started
 Tell me:
 1. What documentation you're building
 2. Who it's for
 3. What they should be able to do after
 I'll ask follow-up questions, then we'll build something people actually want to read.
@@ -0,0 +1,218 @@
 # Configuration Reference
 Essential `docusaurus.config.ts` options. Not exhaustive—see [Docusaurus docs](https://docusaurus.io/docs/api/docusaurus-config) for everything.
 ---
 ## Minimum Viable Config
 ```typescript
 const config = {
  title: 'Project Name',
  url: 'https://docs.example.com',
  baseUrl: '/',
  presets: [
    ['classic', {
      docs: { routeBasePath: '/' },  // Docs at root
      blog: false,                    // Disable if not using
      theme: { customCss: './src/css/custom.css' },
    }],
  ],
 };
 ```
 My opinion: Start minimal. Add complexity only when you need it.
 ---
 ## The Options That Actually Matter
 ### Site Identity
 ```typescript
 title: 'Your Project',           // Browser tab, search results
 tagline: 'One sentence pitch',   // Shows in default homepage
 favicon: 'img/favicon.ico',
 ```
 ### URLs
 ```typescript
 url: 'https://docs.example.com', // Production URL (no trailing slash)
 baseUrl: '/',                    // Usually '/' unless in subdirectory
 trailingSlash: false,            // Pick one and stick with it
 ```
 **Opinion:** `trailingSlash: false`. It's cleaner and most platforms handle it correctly.
 ### Build Behavior
 ```typescript
 onBrokenLinks: 'throw',           // Fail build on broken links
 onBrokenMarkdownLinks: 'throw',   // Same for markdown links
 ```
 **Opinion:** Always `throw` in production. `warn` during development is OK.
 ---
 ## Preset: Classic (Use This)
 ```typescript
 presets: [
  ['classic', {
    docs: {
      sidebarPath: './sidebars.ts',
      routeBasePath: '/',           // Docs as homepage
      editUrl: 'https://github.com/org/repo/edit/main/',
      showLastUpdateTime: true,     // Shows git commit time
    },
    blog: {
      showReadingTime: true,
      blogSidebarCount: 'ALL',
    },
    theme: {
      customCss: './src/css/custom.css',
    },
  }],
 ],
 ```
 ### Docs-Only Mode
 Set `routeBasePath: '/'` and either `blog: false` or keep blog at `/blog`.
 ---
 ## Theme Config: What Readers See
 ### Navbar
 ```typescript
 themeConfig: {
  navbar: {
    title: 'Project',
    logo: { alt: 'Logo', src: 'img/logo.svg' },
    items: [
      { type: 'docSidebar', sidebarId: 'docs', label: 'Docs' },
      { to: '/blog', label: 'Blog' },
      { href: 'https://github.com/...', label: 'GitHub', position: 'right' },
    ],
  },
 }
 ```
 **Opinion:** Keep navbar items under 5. More than that, use dropdowns.
 ### Color Mode
 ```typescript
 colorMode: {
  defaultMode: 'light',           // Or 'dark'
  respectPrefersColorScheme: true, // Honor system preference
 },
 ```
 **Opinion:** Always `respectPrefersColorScheme: true`. Don't force your preference.
 ### Sidebar Behavior
 ```typescript
 docs: {
  sidebar: {
    hideable: true,              // Let users collapse it
    autoCollapseCategories: true, // Only one category expanded
  },
 },
 ```
 ### Search (Algolia)
 ```typescript
 algolia: {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',  // Public search-only key
  indexName: 'YOUR_INDEX',
 },
 ```
 Apply at [Algolia DocSearch](https://docsearch.algolia.com/apply). It's free for open source.
 ---
 ## Plugins Worth Adding
 ### Client-Side Redirects
 ```typescript
 plugins: [
  ['@docusaurus/plugin-client-redirects', {
    redirects: [
      { from: '/old-page', to: '/new-page' },
    ],
  }],
 ],
 ```
 Use for moved pages. Don't leave 404s.
 ### Ideal Image
 ```typescript
 ['@docusaurus/plugin-ideal-image', {
  quality: 85,
  max: 1030,
  min: 640,
 }],
 ```
 Auto-generates responsive images. Worth it for image-heavy docs.
 ---
 ## Things I Never Configure
 These defaults are fine:
 - `i18n` (unless you actually have translations ready)
 - `onDuplicateRoutes` (the default `warn` is fine)
 - `staticDirectories` (default `static` works)
 - `titleDelimiter` (the `|` is universal)
 Don't add config for things you're not using. It's clutter.
 ---
 ## Config Anti-Patterns
 **Don't:** Copy entire example configs and modify
 **Do:** Start minimal, add what you need
 **Don't:** Set `onBrokenLinks: 'ignore'` to "fix" build errors
 **Do:** Actually fix the broken links
 **Don't:** Add `customFields` unless you're using them in code
 **Do:** Keep config lean
 ---
 ## Environment Variables
 For values that change between environments:
 ```typescript
 const config = {
  url: process.env.SITE_URL || 'http://localhost:3000',
  customFields: {
    apiUrl: process.env.API_URL,
  },
 };
 ```
 Access in components:
 ```javascript
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 const { siteConfig } = useDocusaurusContext();
 const apiUrl = siteConfig.customFields.apiUrl;
 ```
@@ -0,0 +1,216 @@
 # Deployment
 Getting your docs live. Pick the platform that fits your workflow.
 ---
 ## Quick Decision
 | Platform | Best For | Effort |
 |----------|----------|--------|
 | **Vercel** | Teams already using Vercel | Lowest |
 | **Netlify** | Need redirects, forms, functions | Low |
 | **GitHub Pages** | Open source, simple hosting | Low |
 | **Cloudflare Pages** | Global performance, free tier | Low |
 **My recommendation:** Vercel or Netlify for most projects. GitHub Pages if you want everything in one repo.
 ---
 ## Vercel
 ### Setup
 1. Push to GitHub
 2. Import at vercel.com
 3. Done—it auto-detects Docusaurus
 ### Config (vercel.json, usually not needed)
 ```json
 {
  "buildCommand": "npm run build",
  "outputDirectory": "build"
 }
 ```
 Vercel handles this automatically. Only add if you need overrides.
 ---
 ## Netlify
 ### Setup
 1. Push to GitHub
 2. Connect at app.netlify.com
 3. Build command: `npm run build`
 4. Publish directory: `build`
 ### Config (netlify.toml)
 ```toml
 [build]
  command = "npm run build"
  publish = "build"
 [[redirects]]
  from = "/old-path"
  to = "/new-path"
  status = 301
 ```
 **Opinion:** Netlify's redirect handling is cleaner than most.
 ---
 ## GitHub Pages
 ### Config
 ```typescript
 // docusaurus.config.ts
 const config = {
  url: 'https://username.github.io',
  baseUrl: '/repo-name/',  // or '/' for username.github.io
  organizationName: 'username',
  projectName: 'repo-name',
  trailingSlash: false,
 };
 ```
 ### GitHub Actions (recommended)
 `.github/workflows/deploy.yml`:
 ```yaml
 name: Deploy
 on:
  push:
    branches: [main]
 permissions:
  contents: read
  pages: write
  id-token: write
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: build
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment
 ```
 Enable Pages in repo settings → Pages → Source: GitHub Actions.
 ---
 ## Cloudflare Pages
 ### Setup
 1. Connect repo at pages.cloudflare.com
 2. Framework: None (not auto-detected well)
 3. Build command: `npm run build`
 4. Output directory: `build`
 ### Why Cloudflare
 - Fastest global CDN
 - Generous free tier
 - Web analytics included
 ---
 ## Pre-Deployment Checklist
 Before pushing:
 ```bash
 # 1. Build locally first
 npm run build
 # 2. Test the build
 npm run serve
 # 3. Check for broken links (build will fail if onBrokenLinks: 'throw')
 # 4. Verify all images load
 # 5. Test search works (if Algolia configured)
 ```
 ---
 ## Custom Domain
 All platforms support custom domains. General steps:
 1. Add domain in platform settings
 2. Update DNS:
   - `A` record to platform IP, or
   - `CNAME` to platform URL
 3. Wait for SSL certificate (automatic, usually minutes)
 4. Update `url` in docusaurus.config.ts
 **DNS propagation:** Can take up to 48 hours. Usually much faster.
 ---
 ## Environment-Specific Builds
 For staging vs production:
 ```typescript
 const isProd = process.env.NODE_ENV === 'production';
 const config = {
  url: isProd
    ? 'https://docs.example.com'
    : 'https://staging-docs.example.com',
 };
 ```
 Or use platform environment variables.
 ---
 ## Common Issues
 ### Build Fails Locally But Worked Before
 ```bash
 rm -rf node_modules .docusaurus
 npm ci
 npm run build
 ```
 ### Build Works Locally, Fails in CI
 - Check Node.js version matches
 - Check for case-sensitive filename issues (Linux is case-sensitive, macOS isn't)
 - Check for absolute paths that only exist on your machine
 ### "Page Not Found" After Deploy
 - Check `baseUrl` matches your hosting path
 - Check `trailingSlash` is consistent
 - Clear CDN cache if platform supports it
@@ -0,0 +1,241 @@
 # Diátaxis Patterns for Docusaurus
 Templates and patterns for each documentation quadrant.
 ---
 ## Tutorial Template
 **Purpose:** Take someone from zero to "I built something!"
 **Filename:** `getting-started/your-first-[thing].md`
 ```markdown
 ---
 title: "Build Your First [Thing]"
 description: "Create a working [thing] in 10 minutes"
 ---
 # Build Your First [Thing]
 By the end of this tutorial, you'll have a working [thing] that [does X].
 ## What You'll Build
 [Screenshot or diagram of the end result]
 ## Prerequisites
 - [Specific version] of [tool] installed
 - Basic familiarity with [concept] (see [link] if new)
 ## Step 1: [Action verb] the [thing]
 [One action, one visible result]
 You should see:
 ```
 [Expected output]
 ```
 ## Step 2: [Next action]
 [Continue pattern...]
 ## What You've Built
 You now have a [thing] that [capability].
 **Next steps:**
 - [Link to how-to guide for customization]
 - [Link to explanation of how it works]
 ```
 **Tutorial Anti-patterns:**
 - "First, let's understand how X works..." → Link instead
 - "You can also do Y..." → One path only
 - "This is simple..." → Never
 ---
 ## How-To Guide Template
 **Purpose:** Help someone accomplish a specific task.
 **Filename:** `guides/how-to-[verb]-[thing].md`
 ```markdown
 ---
 title: "How to [Verb] [Thing]"
 description: "[Outcome] in [context]"
 ---
 # How to [Verb] [Thing]
 [One sentence: what this accomplishes]
 ## What You'll Need
 - [Prerequisite 1]
 - [Prerequisite 2]
 ## Steps
 ### 1. [Action]
 ```bash
 command here
 ```
 ### 2. [Action]
 [Instructions...]
 ## Verification
 [How to confirm it worked]
 ## Troubleshooting
 **[Symptom]:** [Quick fix or link to explanation]
 ```
 **How-to Anti-patterns:**
 - Teaching concepts (that's a tutorial)
 - Listing all options (that's reference)
 - Explaining why (that's explanation)
 ---
 ## Reference Template
 **Purpose:** Describe what something IS, not how to use it.
 **Filename:** `reference/[category]/[item].md`
 ```markdown
 ---
 title: "[Component/API/Config] Reference"
 description: "Complete reference for [thing]"
 ---
 # [Thing] Reference
 [One sentence: what this is]
 ## Properties
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `name` | `string` | required | Brief description |
 | `enabled` | `boolean` | `true` | Brief description |
 ## Examples
 ```javascript
 // Minimal
 { name: "example" }
 // Full
 {
  name: "example",
  enabled: true,
  // ...
 }
 ```
 ## Related
 - [Link to how-to guide using this]
 - [Link to explanation of design]
 ```
 **Reference Anti-patterns:**
 - "To use this, first..." → That's a how-to
 - "This is useful when..." → That's explanation
 - Incomplete tables (every prop documented)
 ---
 ## Explanation Template
 **Purpose:** Help someone understand WHY.
 **Filename:** `concepts/[topic].md`
 ```markdown
 ---
 title: "Understanding [Concept]"
 description: "Why [thing] works the way it does"
 ---
 # Understanding [Concept]
 [Hook: why this matters to the reader]
 ## The Problem
 [What challenge does this solve?]
 ## How [Product] Approaches This
 [Your design decision and reasoning]
 ## Trade-offs
 | Approach | Pros | Cons |
 |----------|------|------|
 | [Option A] | ... | ... |
 | [Option B] | ... | ... |
 **We chose [X] because [reasoning].**
 ## When to Choose Differently
 [Acknowledge alternatives have merit in certain contexts]
 ## Further Reading
 - [External resource]
 - [Related concept in these docs]
 ```
 **Explanation Anti-patterns:**
 - Step-by-step instructions (how-to)
 - Property tables (reference)
 - "Let's build..." (tutorial)
 ---
 ## Deciding Which Type
 Ask yourself:
 ```
 Is the reader trying to LEARN?
 ├── Yes → Tutorial
 └── No
    └── Are they trying to DO something specific?
        ├── Yes → How-to Guide
        └── No
            └── Are they trying to LOOK UP information?
                ├── Yes → Reference
                └── No → Explanation
 ```
 **If you're unsure:** Write it as a how-to first. They're the most commonly needed and easiest to split later.
 ---
 ## Connecting the Quadrants
 Good docs link between types:
 - **Tutorial** → "To learn more about why this works, see [Explanation]"
 - **Tutorial** → "For the full API, see [Reference]"
 - **How-to** → "Prerequisites: complete [Tutorial] first"
 - **How-to** → "For all options, see [Reference]"
 - **Reference** → "For a walkthrough, see [How-to]"
 - **Explanation** → "To try this yourself, see [Tutorial]"
 Never dead-end a reader. Always point them forward.
@@ -0,0 +1,276 @@
 # Writing Guide
 Voice, tone, and language standards for documentation.
 ---
 ## Voice Principles
 ### Be Direct
 Not: "It should be noted that the configuration file needs to be updated."
 Yes: "Update the configuration file."
 Not: "Users may find it helpful to restart the server."
 Yes: "Restart the server."
 ### Address the Reader
 Not: "Developers can use the API to..."
 Yes: "Use the API to..."
 Not: "One might consider..."
 Yes: "Consider..."
 ### Present Tense, Active Voice
 Not: "The file will be created when..."
 Yes: "The file is created when..."
 Not: "The request is processed by the server."
 Yes: "The server processes the request."
 ---
 ## Words That Weaken
 Remove these. They add nothing:
 | Remove | Why |
 |--------|-----|
 | simply, just, easily | Implies difficulty is your fault |
 | obviously, clearly | If it were obvious, you wouldn't write it |
 | please | Unnecessary in instructions |
 | in order to | "To" works |
 | it is important to note that | Just state it |
 | basically | Delete |
 | actually | Delete |
 **Before:** "Simply run the following command to easily set up..."
 **After:** "Run the command to set up..."
 ---
 ## Inclusive Language
 ### Required Replacements
 | Don't Use | Use Instead |
 |-----------|-------------|
 | whitelist / blacklist | allowlist / blocklist |
 | master / slave | primary / replica, main / secondary |
 | master branch | main branch |
 | sanity check | confidence check, validation, smoke test |
 | dummy (value/data) | placeholder, sample, test |
 | cripple | disable, impair, limit |
 | blind to | unaware of, ignoring |
 | crazy, insane | unexpected, surprising, intense |
 | man-hours | person-hours, engineering hours |
 | manpower | workforce, staffing |
 | guys | folks, everyone, team, y'all |
 | he/she, his/her | they, their |
 | normal users | typical users, most users |
 ### Writing About People
 **Disability:**
 - Not: "suffers from," "victim of," "wheelchair-bound"
 - Yes: "has," "uses a wheelchair," "with [condition]"
 **Age:**
 - Not: "the elderly," "seniors"
 - Yes: "older adults"
 **Experience level:**
 - Not: "for dummies," "idiot's guide"
 - Yes: "introduction," "getting started"
 ### Cultural Sensitivity
 - Avoid US-centric examples (Thanksgiving, Super Bowl, Fahrenheit)
 - Use ISO date format: 2024-01-15, not 01/15/2024
 - Use 24-hour time or specify timezone
 - Don't assume everyone celebrates the same holidays
 ---
 ## Second Person "You"
 Always address the reader directly:
 Not: "The user should configure their settings."
 Yes: "Configure your settings."
 Not: "Developers will need to install..."
 Yes: "Install..."
 **When to use "we":**
 - Only when the reader is genuinely working WITH you
 - "We'll build this together" (in a collaborative tutorial)
 - Never use "we" to mean "our company"
 ---
 ## Code in Prose
 ### Commands
 Use backticks and be specific:
 Not: "Run the build command."
 Yes: "Run `npm run build`."
 ### Filenames and Paths
 Always in backticks: `docusaurus.config.ts`, `src/pages/`
 ### Configuration Values
 In backticks: Set `trailingSlash` to `false`.
 ### Placeholders
 Use angle brackets and ALL_CAPS:
 ```bash
 git clone https://github.com/<YOUR_USERNAME>/<REPO_NAME>
 ```
 Not `{username}` or `$USERNAME` in documentation prose.
 ---
 ## Headings
 ### Capitalization
 Use sentence case, not title case:
 Not: "How To Configure Your Build Settings"
 Yes: "How to configure your build settings"
 ### Parallel Structure
 If one heading starts with a verb, they all should:
 **Good:**
 - Install dependencies
 - Configure the project
 - Deploy to production
 **Bad:**
 - Installation
 - Configure the project
 - Deploying to production
 ### Depth
 Never go past H3 in a single page. If you need H4, the page is too complex—split it.
 ---
 ## Lists
 ### When to Use Bullets vs. Numbers
 **Numbers:** When order matters (steps, priority)
 **Bullets:** When order doesn't matter (features, options)
 ### List Formatting
 Each item should be grammatically parallel:
 **Good:**
 - Configure the database
 - Set up authentication
 - Deploy the application
 **Bad:**
 - Database configuration
 - Set up authentication
 - The application should be deployed
 ### Sentence Fragments OK
 In lists, sentence fragments are fine:
 - Fast builds
 - Hot reloading
 - TypeScript support
 ---
 ## Examples
 ### Show, Don't Tell
 Not: "The configuration accepts various options for customization."
 Yes:
 ```javascript
 {
  theme: 'dark',
  language: 'en',
 }
 ```
 ### Minimal, Then Complete
 Show the simplest working example first:
 ```javascript
 // Minimal
 { name: 'my-project' }
 ```
 Then show comprehensive:
 ```javascript
 // With all options
 {
  name: 'my-project',
  version: '1.0.0',
  // ...
 }
 ```
 ### Comments in Code
 Use comments to explain WHY, not WHAT:
 ```javascript
 // Good: Explains reasoning
 timeout: 30000, // Matches API's default request timeout
 // Bad: States the obvious
 timeout: 30000, // Set timeout to 30000
 ```
 ---
 ## Error Messages
 When documenting errors:
 1. Show the exact error message the user sees
 2. Explain what caused it
 3. Give the fix
 ```
 Error: Cannot find module 'react'
 ```
 **Cause:** Dependencies aren't installed.
 **Fix:** Run `npm install` in your project directory.
 ---
 ## Checklist Before Publishing
 - [ ] Title describes what the reader will DO
 - [ ] Description is under 160 characters
 - [ ] No "simple," "easy," "just," or "obviously"
 - [ ] All code examples tested and working
 - [ ] Links to related pages (no dead ends)
 - [ ] Heading structure: H1 → H2 → H3 only
 - [ ] Inclusive language throughout