Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
185 lines (135 loc) · 7.88 KB

CONTRIBUTING.md

File metadata and controls

185 lines (135 loc) · 7.88 KB

Contributing to NVIDIA OpenShell Documentation

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 now live in fern/versions/latest/pages/, and navigation is defined in fern/versions/latest.yml. The docs/ tree is kept for legacy Sphinx builds and migration/reference work. Do not update docs/ unless you are explicitly asked to do so.

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 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.

The skills live in .agents/skills/ and follow the style guide below automatically. To use one, ask your 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 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

Preview Fern docs first, then use the legacy Sphinx build only if you explicitly need it for comparison.

To preview Fern docs locally, run:

fern docs dev

To run non-interactive validation, run:

fern check

PRs that touch fern/** also get a preview from .github/workflows/branch-docs.yml when FERN_TOKEN is available to the workflow.

If you need the legacy Sphinx build during the transition, use:

mise run docs

To serve the legacy docs locally with automatic rebuilds, run:

mise run docs:serve

Writing Conventions

Format

  • Published docs use Fern MDX under fern/versions/latest/pages/.
  • Every page starts with YAML frontmatter. Use title and description on every page, then add page-level metadata like sidebar-title, keywords, tags, and position when the page needs them.
  • Include the SPDX license header after frontmatter: 
    {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  SPDX-License-Identifier: Apache-2.0 */}
  • Do not repeat the page title as a body H1. Fern renders the title from frontmatter.

Frontmatter Template

---
title: "Page Title"
sidebar-title: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing"
tags:
  - 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. When migrating from docs/, combine the legacy topics and tags into keywords.
  • tags is an optional array for preserving legacy doc taxonomy or changelog tags. Fern does not treat tags as SEO metadata on ordinary pages, so still populate keywords.
  • 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 fern/versions/latest.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.

For explicit page and folder entries in fern/versions/latest.yml, put the relative slug: there instead of in frontmatter. Use skip-slug: true when a child page should live at the parent section path.

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 $: 
    openshell gateway start
  • 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>-<description>/<username>.
  2. Make your changes.
  3. Preview locally with fern docs dev.
  4. Run fern check.
  5. Run mise run pre-commit to catch formatting issues.
  6. Open a PR with docs: as the conventional commit type.
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:

feat(cli): add --gpu flag to gateway start

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.