Documentation Standards

Documentation Standards#

Voice and Tone#

Writing Style#

  • Use active voice

  • Write in second person (“you”) for instructions

  • Maintain professional, technical tone

  • Be concise and direct

  • Use present tense

Examples:

- The configuration file will be created by the operator
+ The operator creates the configuration file

- One should ensure that all prerequisites are met
+ Ensure all prerequisites are met

Terminology Standards#

Product Names#

  • “AMD GPU Operator” (not “GPU operator” or “gpu-operator”)

  • “Kubernetes” (not “kubernetes” or “K8s”)

  • “AMD ROCm™” (not “ROCM” or “rocm”)

Technical Terms#

Term

Usage Notes

AMD GPU driver

Standard term for the driver. Don’t use “AMDGPU driver” or “GPU driver” alone

worker node

Standard term for cluster nodes. Don’t use “worker” or “node” alone

DeviceConfig

One word, capital ‘D’ and ‘C’ when referring to the resource

container image

Use instead of just “image”

pod

Lowercase unless starting a sentence

namespace

Lowercase unless starting a sentence

Acronym Usage#

Always expand acronyms on first use in each document:

  • NFD (Node Feature Discovery)

  • KMM (Kernel Module Management)

  • CRD (Custom Resource Definition)

  • CR (Custom Resource)

Formatting Standards#

Headers#

  • Use title case for all headers

  • Add blank line before and after headers

# Main Title

## Section Title

### Subsection Title

Code Blocks#

  • Always specify language for syntax highlighting

  • Use inline code format (code) for:

    • Command names

    • File names

    • Variable names

    • Resource names

  • Use block code format (```) for:

    • Command examples

    • YAML/JSON examples

    • Configuration files

    • Output examples

Examples:

Install using `helm`:

```bash
helm install amd-gpu-operator rocm/gpu-operator-helm
```

Create a configuration:

```yaml
apiVersion: amd.com/v1alpha1
kind: DeviceConfig
metadata:
  name: example
```

Lists#

  • Maintain consistent indentation (2 spaces)

  • End each list item with punctuation

  • Add blank line between list items if they contain multiple sentences or code blocks

Admonitions#

Use consistent formatting for notes, warnings, and tips:

```{note}
Important supplementary information.

Warning

Critical information about potential problems.

Tip

Helpful advice for better usage.

### Tables

- Use tables for structured information
- Include header row
- Align columns consistently
- Add blank lines before and after tables

Example:

```markdown
| Parameter | Description | Default |
|-----------|-------------|---------|
| `image` | Container image path | `rocm/gpu-operator:latest` |
| `version` | Driver version | `6.2.0` |

Document Structure#

Standard Sections#

Every document should include these sections in order:

  1. Title (H1)

  2. Brief overview/introduction

  3. Prerequisites (if applicable)

  4. Main content

  5. Verification steps (if applicable)

  6. Troubleshooting (if applicable)

Example Template#

# Feature Title

Brief description of the feature or component.

## Prerequisites

- Required components
- Required permissions
- Required resources

## Overview

Detailed description of the feature.

## Configuration

Configuration steps and examples.

## Verification

Steps to verify successful implementation.

## Troubleshooting

Common issues and solutions.

File Naming#

  • Use lowercase

  • Use hyphens for spaces

  • Be descriptive but concise

  • Include category prefix when applicable

Examples:

  • install-kubernetes.md

  • upgrade-operator.md