Documentation Contribution Guidelines

When opening a merge request for documentation updates:

• The target branch should be develop for Core Network and RAN, and dev for FlexRIC.
• Include the documentation label when creating a merge request.
• If you are working on a feature branch, ensure you regularly rebase it onto develop (for Core Network/RAN) or dev (for FlexRIC) to stay up to date and minimize merge conflicts.
• For each logical change, create a separate, clean commit with a clear and descriptive commit message that explains the purpose of the change. For example, adding a new handover-tutorial and updating the feature set should be made as two distinct commits, since they represent separate logical changes.

For the Reviewer:

Please verify that all guidelines are followed before approving the merge request.

Folder Structure and File Organization

To maintain a clean, consistent, and well-organized documentation layout, please follow the structure below.

Images and Diagrams

Store all image files under the dedicated folder:

docs/images/

Do not place images directly under the docs/ directory.

❌ Incorrect: docs/amf.png

✅ Correct: docs/images/amf.png

Supported image file types are .png, .jpg/.jpeg, .svg, .webp, .ico or .gif.

Notes

• In the openairinterface5g repository, several subfolders contain their own images/ directories—for example, doc/images and doc/testbenches_doc_resources/images. Make sure to place each image in the appropriate folder for the section of documentation you are updating.
• In FlexRIC, store all figures in the fig folder.

Results, Logs, and PCAPs

Store all result-related files (such as logs, PCAPs, and similar data) under dedicated folders:

For example, in Core Network:

docs/results/

Always update file paths in Markdown accordingly when adding or modifying the asset links.

New Documentation

When adding a new document, place it in an appropriate, dedicated subfolder rather than directly in docs/. Additionally, give the file a relevant and descriptive name, paying attention to letter casing. If you are unsure about the naming convention, refer to existing files in the same folder for guidance.

❌ Incorrect:

docs/handover-tutorial.md
docs/architecture/UnitTests.md

✅ Correct:

docs/tutorials/handover-tutorial.md
docs/testing/UnitTests.md

---

Avoid Inline HTML

Always use standard Markdown syntax and avoid inline HTML.

Use pure Markdown for titles, images, tables, and formatting to ensure portability and compatibility across Markdown renderers.

Titles

Do not use HTML tables or inline styles for headers.

❌ Incorrect:

<table style="border-collapse: collapse; border: none;">
  <tr>
    <td>
      <a href="http://www.openairinterface.org/">
        <img src="images/oai_final_logo.png" alt="" height=50 width=150>
      </a>
    </td>
    <td>
      <b><font size="5">OpenAirInterface 5G Core Network Deployment: Building Container Images</font></b>
    </td>
  </tr>
</table>

✅ Correct (Markdown):

# OpenAirInterface 5G Core Network Deployment: Building Container Images

Figures

Do not use HTML <figure> or <figcaption> elements for images.

❌ Incorrect:

<figure>
  <img src="./images/5gcn_eBPF_upf.png" alt="UPF architecture using eBPF technology" width="900" height="600" />
  <figcaption><b><font size="5">Figure 1: UPF Architecture: eBPF XDP based</font></b></figcaption>
</figure>

✅ Correct (Markdown):

![This is the UPF architecture using the eBPF technology.](images/5gcn_eBPF_upf.png)

**Figure 1: UPF Architecture – eBPF XDP based**

---

Headings

• Only one top-level heading (# H1) should exist per document.
• Use subsequent heading levels (## to ######) for subheadings.
• Do not add trailing # symbols after headings.

❌ Incorrect:

# OpenAirInterface 5G Core Network
# Workflow and Versioning #
## Manage your own branch
## Merge Requests

✅ Correct:

# OpenAirInterface 5G Core Network
## Workflow and Versioning
### Manage your own branch
### Merge Requests

---

Quoting Code, Files, and Commands

Use single backticks (`) to reference code, files, or commands inline.

Code and Commands

* Use the `--verbose` option to see each command’s execution.  
* We configured a new IP range by adding the `/etc/docker/daemon.json` file.  

For multi-line code blocks, enclose the code within triple backticks (```) and optionally specify a language for syntax highlighting.

```bash
docker --version
docker images
docker ps -a
docker system prune -a
```

Notes

• To make commands copy-friendly, avoid using $ signs and use plain commands.
• Avoid trailing spaces inside triple backticks.
• Always indent or align code properly inside code blocks.
• For variables, functions, or any code-related identifiers, always use inline code formatting (single backticks `) to improve readability.

✅ Correct:

A couple of interesting variables are --verbose, --output-on-failure.

❌ Incorrect:

A couple of interesting variables are –verbose, –output-on-failure.

Collapsible Sections

You can create collapsible sections that expand when clicked — useful for hiding long outputs, logs, or optional details. This feature helps keep your documentation concise while still providing extra information when needed.

Example:

<details>
<summary>Expected Output</summary>

```bash
Docker version 28.0.4, build b8034c0
```

</details>

Rendered Output:

Expected Output

Docker version 28.0.4, build b8034c0

---

Links

Always use Markdown link syntax [link text](URL) instead of pasting raw URLs. Do not add a space between ] and ( — that breaks the link.

✅ Correct:

You can pull the Docker images from [OAI DockerHub](https://hub.docker.com/u/oaisoftwarealliance).

❌ Incorrect:

You can pull the Docker images from https://hub.docker.com/u/oaisoftwarealliance.
[Mosaic5G] (https://openairinterface.org/news/mosaic5g-moves-home-to-the-openairinterface-software-alliance/).
[Jenkins] https://jenkins-oai.eurecom.fr/.

---

Relative Links

Use relative links for navigation within the repository to keep references portable.

Example:

.
├── fed
│   ├── BUILD_IMAGES.md
│   ├── FEATURE_SET.md
│   └── network-functions
│       └── amf.md
├── images
│   └── logo.png
└── README.md

Referencing an Image (from BUILD_IMAGES.md):

![OAI Logo](../images/logo.png)

Linking to Another File (FEATURE_SET.md) in the same directory:

Feature set of this project is defined in the file [FEATURE_SET.md](FEATURE_SET.md).

Linking from a Subfolder to a File One Level Up (from amf.md to BUILD_IMAGES.md):

Refer to the build instructions in [BUILD_IMAGES.md](../BUILD_IMAGES.md).

Linking from a Subfolder to a File Two Levels Up (from amf.md to README.md):

For the main documentation, see [README.md](../../README.md).

---

Section Links

You can create links that point directly to specific sections within your Markdown file. This is useful for easy navigation, especially in long documents.

Example:

# OpenAirInterface

## 5G Core Network (CN5G)

### Building Container Images

Each 5G Network Function (NF) source code is maintained in its own repository.

### Access and Mobility Management Function (AMF)

You can build the AMF image by following the steps in the [Building Container Images](#building-container-images) section.

In the above example, clicking “Building Container Images” will take you directly to that section.

---

Quoting Text

Use the > character to create callout blocks for notes, warnings, or cautions. This helps highlight important information and improves readability.

Example:

> **Note:** When creating a merge request, make sure to select `develop` as the target branch.

Rendered Output:

Note: When creating a merge request, make sure to select develop as the target branch.

---

Tables and Lists in Markdown

Use Markdown syntax only for tables and lists. Avoid HTML tags for consistency.

Tables

Leave a blank line before and after the table for proper Markdown parsing.

Keep header dashes and pipes aligned for readability.

Example:

| Parameter   | Description          | Example     |
|------------|--------------------|------------|
| `IMAGE_TAG` | Docker image version tag | `develop` |
| `NF`        | Network function        | `oai-amf` |

Output:

Parameter	Description	Example
IMAGE_TAG	Docker image version tag	develop
NF	Network function	oai-amf

---

Lists

Always leave a blank line before and after a list. This ensures the list is rendered correctly in Markdown.

✅ Correct:

Unordered:

Core Network Functions:

* AMF – Access and Mobility Management Function  
* SMF – Session Management Function  
* UPF – User Plane Function

Ordered:

To build the image, follow these steps:

1. Clone the repository  
2. Build the image  
3. Verify with `docker images`

Nested List:

OAI Jenkins Pipelines:

* **Image Build Pipelines**
  - RAN-Ubuntu18-Image-Builder
  - RAN-Ubuntu-Jetson-Image-Builder

* **Image Test Pipelines**
  - OAI-CN5G-COTS-UE-Test

❌ Incorrect:

Core Network Functions:
* AMF – Access and Mobility Management Function  
* SMF – Session Management Function  
* UPF – User Plane Function

* Image Build Pipelines
RAN-Ubuntu18-Image-Builder
RAN-Ubuntu-Jetson-Image-Builder

---

Spacing and Line Length

• Maintain consistent spacing between paragraphs and sections.
• Use line breaks to separate logical blocks of text.
• Keep paragraphs concise, ideally 4-8 lines each.
• Organize content into lists or key points wherever possible to enhance clarity.
• Limit lines to 80–100 characters to improve readability.
• Use visual separators like --- to clearly indicate section breaks when needed.

---