> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcb.new/llms.txt
> Use this file to discover all available pages before exploring further.

# README conventions

> Write practical README files for boards and reusable packages

# README conventions

Every board and package must have a `README.md` in its root directory. The
README must identify the artifact, explain its purpose, and give a technically
competent reader enough information to build or use it.

Keep the document current with the source. Remove empty sections, placeholders,
historical plans, and implementation details that do not affect the reader.

## Board README

A board README serves engineers who build, manufacture, flash, or test the
board. Include its purpose, main devices, key interfaces, operating limits, and
the exact build commands. State any required tools or external assets before the
procedure.

Use this structure:

````markdown theme={null}
# <BoardName>

Describe the board, its main function, and its important operating limits.

## Features

- List the main controller or processor.
- List the external interfaces.
- List significant power or safety features.

## Build

State nonstandard prerequisites, then run:

```bash
pcb build <BoardName>.zen
pcb layout <BoardName>.zen
```

Describe the generated output and any expected warnings.

## License

State the applicable license.
````

Add pin assignments, design constraints, firmware instructions, or related
datasheets only when they are required to use the board.

## Package README

A package README serves engineers who import a reusable component or module.
Identify every public symbol and provide one complete import or instantiation
example.

Use this structure:

````markdown theme={null}
# <package_name>

Describe what the package exports and when to use it.

## Usage

```python
load("<package_name>.zen", "ExportedSymbol")
```

## Exports

| Symbol | Description |
|---|---|
| `ExportedSymbol` | State its function and important limits. |

## Configuration

```python
instance = ExportedSymbol(
    required_input = value,
)
```
````

Document required inputs, defaults, units, limitations, and layout constraints
where they affect correct use. Omit the configuration section if the package has
no configurable behavior.

## Style

* Start with purpose and scope. Define a term before using it.
* Use active voice and direct instructions. Use the same term for the same
  concept throughout the document.
* Put identifiers, file names, commands, and pin names in backticks.
* Use numbered steps for procedures and bullets only for short collections.
* Include complete commands and examples. State prerequisites, output, side
  effects, and common failure conditions when relevant.
* Delete redundant prose, speculative plans, and sections with no reader-facing
  content.