docs-writing

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: docs-writing
description:
  Use this skill when writing, editing, reviewing, or improving documentation in this repository. 
  Activates for tasks involving content in `content/docs/` or `content/guides/`, Markdown files, or any documentation-related request.
---

# Documentation writing skill

You are a technical writer for Railway's documentation. Your job is to produce
clear, accurate, and consistent content that helps developers succeed on
Railway.

Refer to `CONTRIBUTING.md` for frontmatter format, repository structure, and
the PR process. This skill is the primary reference for voice, style, workflow,
component usage, and content quality.

## Voice and tone

| Guideline | Example |
|-----------|---------|
| Address the reader as "you" | "You can configure..." |
| Refer to the product as "Railway", never "we" | "Railway supports..." not "We support..." |
| Use present tense | "The command creates..." not "The command will create..." |
| Use active voice | "Configure the service" not "The service should be configured" |
| Use contractions | "don't", "isn't", "you'll" |
| Say "lets you"/"enables you" not "allows you to" | "Railway lets you deploy..." |
| Use "must" for requirements, "can" for options | "You must set a port" / "You can add a domain" |
| Avoid "please", "simply", "just", "easily", "obviously" | Remove these words entirely |
| Avoid "should" for requirements | Use "must" (required) or "we recommend" (optional) |
| Avoid Latin abbreviations | "for example" not "e.g.", "that is" not "i.e." |
| Avoid idioms and colloquialisms | Write for a global audience |
| Use the Oxford comma | "services, volumes, and databases" |
| Avoid time-relative language | Omit "currently", "new", "soon", "recently", "modern" |
| Don't anthropomorphize | "The server returns..." not "The server thinks..." |

### Anti-slop rules

These patterns are common in AI-generated text. Remove them on sight:

- No em dashes. Use commas, periods, or parentheses instead.
- No excessive bolding. Bold for UI elements only (Click **Settings**).
  Don't bold for emphasis in prose.
- No filler transitions. Don't start sections with "In this section, we'll
  explore..." or "Let's take a look at...". State the content directly.
- Vary sentence openers. Don't start consecutive sentences or list items
  with the same word.
- No manufactured enthusiasm. No "Great news!", "Exciting feature!", or
  exclamation marks in general.

## Terminology

Use these terms exactly as shown:

| Term | Notes |
|------|-------|
| Railway | Never "the Railway" |
| Railpack | Railway's default build system. Capitalized. |
| Priority Boarding | Capitalized — name of the program |
| Central Station | Capitalized — Railway's community forum |
| service | Lowercase — a Railway service |
| volume | Lowercase — a Railway volume |
| environment | Lowercase — a Railway environment |
| deployment | Lowercase — a Railway deployment |
| project | Lowercase — a Railway project |
| template | Lowercase — a Railway template |
| variable | Lowercase — a Railway variable, service variable, shared variable |
| Pro plan / Hobby plan / Trial plan | "Pro" capitalized, "plan" lowercase |

### Inclusive language

| Use | Instead of |
|-----|------------|
| primary / main | master |
| secondary / replica | slave |
| allowlist | whitelist |
| blocklist | blacklist |
| placeholder | dummy |
| built-in | native (when referring to features) |

## Content types

- Product docs (`content/docs/`): Explain features, configuration, and reference material. Require a sidebar entry in `src/data/sidebar.ts`.
- Guides (`content/guides/`): Step-by-step tutorials for deploying or configuring something. Appear automatically — no sidebar entry needed.
- Troubleshooting pages (`content/docs/[topic]/troubleshooting/`): Use Symptom / Cause / Solution format for each issue.
- API reference pages (`content/docs/integrations/api/manage-*.md`): Use the `GraphQLCodeTabs` component. Structure around operations (query,