diff --git a/doc/README.md b/doc/README.md index b728768e6f..a4cfe19a2c 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,12 +1,12 @@ # OpenAirInterface documentation overview -This is the general overview page of the OpenAirInterface documentation. +This is the general overview page of the OpenAirInterface documentation. This page groups links to general information, tutorials, design documents, radio integration, and special-purpose libraries. -**IMPORTANT NOTE:** +**IMPORTANT NOTE:** Before reading this documentation, we strongly advise you to keep your own repository rebased on `develop` -or at least to checkout the documentation on the version of the repository you are using. -Then the documentation will better reflect the features available in your repository so that you may avoid some errors. +or at least to checkout the documentation on the version of the repository you are using. +Then the documentation will better reflect the features available in your repository so that you may avoid some errors. Beware if you previously pulled the `develop` branch that your repository may be now behind `develop`. [[_TOC_]] @@ -130,3 +130,4 @@ The other SDRs (AW2S, LimeSDR, ...) have no READMEs. - [formatting](../tools/formatting/README.md) is a clang-format error detection tool - [iwyu](../tools/iwyu/README.md) is a tool to detect `#include` errors - [docker-dev-env](../tools/docker-dev-env/README.md) is a ubuntu24 docker development environment +- [doc_best_practices.md](./doc_best_practices.md): overall best practices for writing documentations diff --git a/doc/doc_best_practices.md b/doc/doc_best_practices.md new file mode 100644 index 0000000000..597eeb4eba --- /dev/null +++ b/doc/doc_best_practices.md @@ -0,0 +1,212 @@ +# Documentation Best Practices + +The following contribution guidelines ensure that all documentation in the +repository is clear, consistent, and readable. Contributors should follow them +to make it easier for other developers and users to understand and maintain the +documentation. + +## Headings + +- Only **one** top-level heading (`# H1`) should exist per document. +- Use subsequent heading levels (`## H2` to `###### H6`) for subheadings. +- Do **not** add trailing `#` symbols after headings. + +**Examples**: + +Incorrect: + +```markdown +# Contribution Guidelines for Developers +# Workflow and Versioning # +## Manage your own branch +## Merge Requests +``` + +Correct: + +```markdown +# Contribution Guidelines for Developers +## Workflow and Versioning +### Manage your own branch +### Merge Requests +``` + +## Quoting Texts + +Use Markdown **blockquotes (`>`)** for notes, tips, or warnings. Blockquotes +clearly separate important information from regular text, helping readers +notice critical instructions or cautionary notes. + +**Examples**: + +```markdown +> **Note:** Ensure all dependencies are installed before building. + +> **Warning:** Do not run the build as sudo. +``` + +## Avoid HTML formatting + +Do **not** use HTML tags like ``, ``, ``, etc. Use standard +Markdown syntax. HTML may not display correctly on all platforms such as +[GitLab](https://about.gitlab.com/), [GitHub](https://github.com/), etc. + +**Examples**: + +Correct (Markdown): + +```markdown +**Bold text** +*Italic text* + +![OAI Logo](./images/oai_final_logo.png) instead of OAI Logo + +| Feature | Description | +|---------------|---------------------------------| +| H1 Heading | Only one per document | +| Blockquotes | For notes and warnings | +``` + +Incorrect (HTML): + +```html +Bold text +Italic text + +OAI Logo + +
+ + + + + + + + +
H1 HeadingOnly one per document
BlockquotesFor notes and warnings
+ +``` + +## Links and references + +- Use Markdown link syntax `[Text](URL)` for all external URLs or references. +- Use `[Text](#section-anchor)` to link to sections within the same document. +- Use `![Alt text](URL_or_path)` to insert images, with descriptive alt text + for accessibility. Do **not** use HTML `
` or `
` elements + for images. +- Always verify that section anchors exist and check all links to prevent + broken references. +- When adding, deleting, or renaming any documentation file, make sure to + update any related references, links, and indexes in the repository including + the [README.md](README.md). + +**Examples**: + +```markdown +- For more information, visit the [OAI + website](http://www.openairinterface.org/). +- See [primer](http://google.github.io/googletest/primer.html) for a quick + introduction. +- The Linux kernel has some [documentation on what a logical change + is](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#separate-your-changes). +- See [OAI CN5G configuration files](#22-oai-cn5g-configuration-files) for + details. +- ![OAI Logo](./images/oai_final_logo.png) +``` + +## Inline code for technical elements + +Enclose **variables, function names, filenames, commands, or any technical identifiers** in backticks (\`). +Inline code formatting improves readability, clearly differentiates technical terms from normal text, and prevents confusion between text and code. + +**Examples**: + +```markdown +- Run the command `./build_oai`. +- See the function `time_manager_start()`. +- On `x86_64` platform the CPU should support `avx2` instruction set. +- The A2 event can be disabled by setting `enable = 0`. +- The logs are stored in `gnb.log` file. +- The default value for User IMSI is `2089900007487`. +- Once installed you can use this configuration file for ptp4l + (`/etc/ptp4l.conf`). +``` + +For **multi-line code blocks**, use triple backticks with a language identifier for syntax highlighting. + +````bash +```bash +docker --version +docker images +docker ps -a +docker system prune -a +``` +```` + +> **Note:** To make commands copy-friendly, **avoid using `$` signs** and use +> plain commands. + +Also ensure: + +- No extra whitespace before backticks. +- The appropriate language (e.g., `bash`, `python`, `yaml`, `json`, etc.) is + specified for syntax highlighting. + +## 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**: + +````markdown +
+Expected Output + +```bash +Docker version 28.0.4, build b8034c0 +``` + +
+```` + +**Rendered Output**: + +
+Expected Output + +```bash +Docker version 28.0.4, build b8034c0 +``` + +
+ +## Lists and Nested Lists Formatting + +- Use `-` or `*` followed by a space for each bullet. +- Indent nested bullets with **4 spaces** under the parent bullet. +- You must leave a blank line before starting a list after a sentence or + paragraph. +- No blank line is needed before a nested list under a parent bullet. + +> This is because we use `mkdocs` to render documentation, which requires these +> rulee. + +## Documentation commits + +- For each logical change in a documentation file, create a separate, + descriptive commit. +- Each commit should clearly describe what was changed and why, so the history + is easy to read and review. +- Use a clear prefix, like `docs:`, to indicate the commit affects + documentation. +- Reference related issues or MRs if applicable, to help trace changes. + + +**Example:** + +``` +docs: add 5G NSA and Faraday Cage testbench setup to Testbenches.md +```