--- # 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/reference/gateway-config.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`. ### 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 ``, ``, and `` for callouts, not bold text. - Use Fern components like `` and `` 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/-/`. 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`.