Documentation Standards¶

This page defines how we document the Open Field Automation (OFA) project. To ensure technical accuracy and version synchronization, we use a Docs-as-Code workflow. Documentation is stored alongside the source code and built into a central static site. All contributors must follow this structure.

The Documentation Split¶

We maintain a strict boundary between "Developer" information and "System" context.

The Golden Rule: If you need a compiler to use the info, put it in the README. If you need a screwdriver or a textbook, put it in the Documentation HUB.

Repository `README.md` (Developer-Level)¶

Purpose: Immediate onboarding for a developer looking at the source files.
Location: Root of every repository.
Content:
- Software dependencies and environment setup.
- Local build, compile, and installation commands.
- Specific configuration keys (e.g., .json or .yaml parameter definitions).
- ROS2 topics/services and EEROS interface descriptions.

The `/docs` Folder (System-Level)¶

Purpose: High-level system context, published to the central OFA Documentation Site.
Location: A dedicated /docs directory in each repository.
Content:
- Hardware: Wiring diagrams, pinouts, and Bill of Materials (BOM).
- Theory: Mathematical models and kinematic derivations.
- Manuals: Assembly guides, calibration steps, and field testing procedures.

We use Zensical to generate our website

A CI/CD pipeline gathers the docs/ directories from all repositories into a single unified directory. For details, please refer to the Documentation Hub Repo.
To generate the documentation from the gathered markdown files, we use the static site generator Zensical.
Zensical provides many authoring tools, such as this info block. Please refer to the Zensical Authoring Documentation to explore all the options.

Formatting Standards¶

The "Bridge" Standard¶

The top of every README.md must link to its corresponding section on the published documentation site to guide users from the code to the system context. On the other hand, the main landing page of a module (index.md) must link to the module repo.

Mathematics¶

Use LaTeX for all formulas to ensure readability. * Inline: Use $v = r \cdot \omega$ for math within a sentence. * Display: Use $$a = \frac{v_2 - v_1}{t}$$ for standalone equations.

Assets & Images¶

Store images in docs/assets/ within your repository.
Use relative paths in Markdown: ![Description](./assets/image.png).
Requirement: Use high-contrast diagrams or annotated photos for all hardware assembly steps.

Linking between `docs/` pages¶

Ensure all links between documents in the /docs folder are relative so they work both in GitLab's preview and on the generated website.

Repository Structure Template¶

repo-name/
├── docs/                 # Gathered by central Docs-Repo
│   ├── assets/           # Diagrams and photos
│   └── index.md          # Main landing page for this module
├── ***                   # Source code, CAD files, ...
└── README.md             # Developer Quick-start

`index.md` Template¶

---
title: ... (Documentation site title, will be displayed in the navigation sidebar) ...
description: ... (Documentation site description) ...
---

# [Module or Rover Name] Documentation

> **Link to module repo: [...](...)**

---

## Overview
... (Content here) ...

`README.md` Template¶

# [Module or Rover Name]

> **Part of the [Open Field Automation (OFA)](https://gitlab.ost.ch/open-field-automation-ofa) Ecosystem**   
> **For a detailed documentation of the project, please refer to the [Documentation HUB](https://documentation-hub-e42a0b.pages.ost.ch/)**   
> **For a detailed documentation of this [module/rover], please refer to the [Module/Rover Documentation](https://documentation-hub-e42a0b.pages.ost.ch/subgroup/repo)**

---

## Overview
... (Content here) ...

---

**Maintained by:** [OST - Eastern Switzerland University of Applied Sciences](https://www.ost.ch) and [BFH - Bern University of Applied Sciences](https://www.bfh.ch/)

Note: If a repo is stored in modules/interfaces/module-name, then the link to the documentation will be https://documentation-hub-e42a0b.pages.ost.ch/modules/interfaces/module-name.