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:

# <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:

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

Toolchain

Registry

Examples

README conventions

README conventions

Board README

Package README

Style

​README conventions

​Board README

​Package README

​Style

README conventions

Board README

Package README

Style