OpenShell/docs/CONTRIBUTING.mdx

---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Contributing to NVIDIA OpenShell Documentation"
description: ""
---
This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR.

The published docs live in `docs/`, navigation is defined in `docs/index.yml`, and `fern/` contains the site config, components, and theme assets.

## Use the Agent Skills

If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch.

| Skill | What it does | When to use |
|---|---|---|
| `update-docs-from-commits` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. |
| `build-from-issue` | Plans and implements work from a GitHub issue, including doc updates. | When working from an issue that has doc impact. |

These contributor workflows live in `.agents/skills/` and follow the style guide below automatically. They are separate from the public skills in `skills/`, which help users operate OpenShell and can be installed without cloning the repository. To use a contributor skill, ask your repository-aware agent to run it (e.g., "catch up the docs for everything merged since v0.2.0").

## When to Update Docs

Update documentation when your change:

- Adds, removes, or renames a CLI command or flag.
- Changes default behavior or configuration.
- Adds, removes, renames, or changes defaults for gateway TOML fields or driver-specific config options. Update `docs/how-it-works/gateways/configuration.mdx` for these changes.
- Adds a new feature that users interact with.
- Fixes a bug that the docs describe incorrectly.
- Changes an API, protocol, or policy schema.

## Building Docs Locally

Use the local `mise` tasks for preview and validation, or run the Fern CLI directly from `fern/` if you already have it installed.

To preview Fern docs locally, run:

```shell
mise run docs:serve
```

To run non-interactive validation, run:

```shell
mise run docs
```

If you already have the Fern CLI installed, the equivalent commands from `fern/` are `fern docs dev` and `fern check`.

PRs that touch `docs/**` or `fern/**` are validated by `.github/workflows/branch-docs.yml`, and they also get a preview when `FERN_TOKEN` is available to the workflow.

## Writing Conventions

### Format

- Published docs use Fern MDX under `docs/`.
- Every page starts with YAML frontmatter. Use `title` and `description` on every page, then add page-level metadata like `sidebar-title`, `keywords`, and `position` when the page needs them.
- Include the SPDX license header as YAML comments inside frontmatter:

  ```text
  ---
  # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  # SPDX-License-Identifier: Apache-2.0
  title: "Page Title"
  ---
  ```

- Do not repeat the page title as a body H1. Fern renders the title from frontmatter.

### Frontmatter Template

```yaml
---
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
title: "Page Title"
sidebar-title: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing"
---
```

- `title` sets the page heading and browser title.
- `sidebar-title` sets the shorter label in the sidebar when the full page title is too long.
- `keywords` is a comma-separated string for page metadata.
- `position` controls ordering for pages discovered through a `folder:` entry.
- `slug` optionally overrides the page URL with a full path from the docs root.

For explicit entries in `docs/index.yml`, keep `page:`. Fern still requires it. If the page defines `sidebar-title`, set `page:` to that value. Otherwise set `page:` to the frontmatter `title`.

Keep every page URL equal to its file path under `docs/`, without `.mdx`. Fern builds URLs from nav labels and slugs, not from file paths, so rename the file when you rename a page, and add a redirect in `fern/docs.yml` for the old URL. When a nav label does not produce the file name, for example `TypeScript`, which Fern turns into `type-script`, set a relative `slug:` on the entry in `docs/index.yml`. `mise run docs` runs `mise run docs:nav`, which fails when a page URL differs from its file path, when a nav label differs from the page's sidebar name, when a page is missing from the navigation, or when a redirect points to a page that does not exist.

### Page Structure

1. Frontmatter `title` and `description`, plus any relevant page metadata.
2. A one- or two-sentence introduction stating what the page covers.
3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader.
4. A "Next Steps" section at the bottom linking to related pages when it helps the reader continue.

## Style Guide

Write like you are explaining something to a colleague. Be direct, specific, and concise.

### Voice and Tone

- Use active voice. "The CLI creates a gateway" not "A gateway is created by the CLI."
- Use second person ("you") when addressing the reader.
- Use present tense. "The command returns an error" not "The command will return an error."
- State facts. Do not hedge with "simply," "just," "easily," or "of course."

### Things to Avoid

These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review.

| Pattern | Problem | Fix |
|---|---|---|
| Unnecessary bold | "This is a **critical** step" on routine instructions. | Reserve bold for UI labels, parameter names, and genuine warnings. |
| Em dashes everywhere | "The gateway — which runs in Docker — creates sandboxes." | Use commas or split into two sentences. Em dashes are fine sparingly but should not appear multiple times per paragraph. |
| Superlatives | "OpenShell provides a powerful, robust, seamless experience." | Say what it does, not how great it is. |
| Hedge words | "Simply run the command" or "You can easily configure..." | Drop the adverb. "Run the command." |
| Emoji in prose | "🚀 Let's get started!" | No emoji in documentation prose. |
| Rhetorical questions | "Want to secure your agents? Look no further!" | State the purpose directly. |

### Formatting Rules

- End every sentence with a period.
- Use `code` formatting for CLI commands, file paths, flags, parameter names, and values.
- Use `shell` code blocks for copyable CLI examples. Do not prefix commands with `$`:

  ```shell
  openshell gateway add http://127.0.0.1:18080 --local --name local
  ```

- Use `text` code blocks for transcripts, log output, and examples that should not be copied verbatim.
- Use tables for structured comparisons. Keep tables simple (no nested formatting).
- Use Fern components like `<Note>`, `<Tip>`, and `<Warning>` for callouts, not bold text.
- Use Fern components like `<Steps>` and `<Tabs>` when the page clearly benefits from them.
- Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify."
- Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage."
- Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses.

### Word List

Use these consistently:

| Use | Do not use |
|---|---|
| gateway | Gateway (unless starting a sentence) |
| sandbox | Sandbox (unless starting a sentence) |
| CLI | cli, Cli |
| API key | api key, API Key |
| NVIDIA | Nvidia, nvidia |
| OpenShell | Open Shell, openShell, Openshell, openshell |
| mTLS | MTLS, mtls |
| YAML | yaml, Yaml |

## Submitting Doc Changes

1. Create a branch following the project convention: `docs/<issue-id>-<short-description>/<github-username>`.
2. Make your changes.
3. Preview locally with `mise run docs:serve`.
4. Run `mise run docs`.
5. Run `mise run pre-commit` to catch formatting issues.
6. Open a PR with `docs:` as the conventional commit type.

```text
docs: update gateway deployment instructions
```

If your doc change accompanies a code change, include both in the same PR and use the code change's commit type:

```text
feat(cli): add gateway registration flag
```

## Reviewing Doc PRs

When reviewing documentation:

- Check that the style guide rules above are followed.
- Watch for LLM-generated patterns (excessive bold, em dashes, filler).
- Verify code examples are accurate and runnable.
- Confirm cross-references and links are not broken.
- Preview the page with `fern docs dev`, run `fern check`, and, if available, review the PR preview from `branch-docs.yml`.