From a596731f674a7a6def293198e3b58c0737e0e28d Mon Sep 17 00:00:00 2001 From: Oleg Lukasonok Date: Thu, 30 Jul 2026 22:58:08 +0300 Subject: [PATCH] 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) --- README.md | 54 ++++++- SKILL.md | 185 +++++++++++++++++++++ references/config-reference.md | 218 +++++++++++++++++++++++++ references/deployment.md | 216 +++++++++++++++++++++++++ references/diataxis-patterns.md | 241 ++++++++++++++++++++++++++++ references/writing-guide.md | 276 ++++++++++++++++++++++++++++++++ 6 files changed, 1189 insertions(+), 1 deletion(-) create mode 100644 SKILL.md create mode 100644 references/config-reference.md create mode 100644 references/deployment.md create mode 100644 references/diataxis-patterns.md create mode 100644 references/writing-guide.md diff --git a/README.md b/README.md index 20e8d36..d526a99 100644 --- a/README.md +++ b/README.md @@ -1 +1,53 @@ -# documentation-docusaurus \ No newline at end of file +# 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). diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..e6023d0 --- /dev/null +++ b/SKILL.md @@ -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 + + +``` + +Details for optional deep-dives: +```mdx +
+Why does this matter? +...explanation that most readers can skip... +
+``` + +**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. diff --git a/references/config-reference.md b/references/config-reference.md new file mode 100644 index 0000000..6aa8109 --- /dev/null +++ b/references/config-reference.md @@ -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; +``` diff --git a/references/deployment.md b/references/deployment.md new file mode 100644 index 0000000..2cc41e9 --- /dev/null +++ b/references/deployment.md @@ -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 diff --git a/references/diataxis-patterns.md b/references/diataxis-patterns.md new file mode 100644 index 0000000..495ebc1 --- /dev/null +++ b/references/diataxis-patterns.md @@ -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. diff --git a/references/writing-guide.md b/references/writing-guide.md new file mode 100644 index 0000000..7d4020f --- /dev/null +++ b/references/writing-guide.md @@ -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// +``` + +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