Writing Documentation

Our project utilizes a structured approach to documentation to ensure clarity and ease of access for all users. All documentation is written in Markdown and stored within the docs directory of the repository. The first level of directories under docs corresponds to the main sections of our documentation site:

• overview
• administrators-guide
• user-guide
• development-guide
• about

We use MkDocs along with the Material for MkDocs theme to generate a professional and user-friendly documentation site from this structure.

Partially generated documentation

While most of the documentation is handwritten by the core team or contributors, the API documentation in the development guide section is auto-generated using the crd-ref-docs tool from Elastic.

This document is auto-generated by a GitHub Actions workflow so you should never need to do so manually.

If for some reason you do need to, here is how.

Assuming you're located in the root of the repository, execute the following to update the API document.

go install github.com/elastic/crd-ref-docs
crd-ref-docs --config=./crd-ref-docs-config.yml --source-path=./api --renderer=markdown --output-path=./docs/development-guide/00_api.md

Viewing the documentation locally

To preview documentation changes locally, you can run MkDocs in “serve” mode. This builds the site and starts a local web server with live reload.

Prerequisites

Documentation tooling is Python-based. We recommend using a virtual environment so you don’t need to install packages system-wide (and to avoid externally-managed-environment errors on macOS/Homebrew Python).

Create and use a virtual environment

From the repository root:

python3 -m venv venv
source venv/bin/activate

Install the documentation dependencies:

pip3 install -r requirements.txt

Tip

If you previously tried pip3 install -r requirements.txt without a virtual environment and saw an error like externally-managed-environment, this is expected on some systems. Using a virtual environment is the recommended fix.

Serve the docs

Start the local docs server:

python -m mkdocs serve

MkDocs will print the local URL to open in your browser (for example http://127.0.0.1:8000/opr-paas/).

Tip

Use python -m mkdocs serve instead of mkdocs serve. This ensures you run MkDocs from the currently activated virtual environment, so installed plugins (for example the kroki plugin) are found correctly.

Stopping and re-running

• Stop the server with Ctrl+C
• Leave the virtual environment with:

deactivate

• Next time you want to preview docs again:

source venv/bin/activate
python -m mkdocs serve

Writing Clear and Effective Documentation

When contributing to the documentation, please aim to keep your writing simple and factual. Clear and concise documentation helps users understand and utilize our project more effectively.

Tips for Writing Good Documentation

Be Concise and Direct: Use straightforward language and get to the point quickly. Avoid unnecessary words or overly complex sentences.

Use Active Voice: Write in active voice to make your writing more engaging and easier to understand. For example, we would prefer the use of "Install the package using..." over "The package can be installed using...".

Organize Content Logically: Break down information into logical sections and use headings and subheadings to guide the reader. This makes it easier for users to find the information they need.

Ensure that you place your documentation in the right subsection for your intended reader.

Use Lists and Bullet Points: When presenting multiple items or steps, use lists to improve readability.

Include Examples and Call-Outs: Provide code snippets or command-line examples where applicable to illustrate your points.

Tip

Use call-outs like this to highlight important information. You can use "note", "abstract", "info", "tip", "success", "question", "warning", "failure", "danger", "bug", "example" and "quote".

See the docs for more information.

Maintain Consistent Formatting: Try to follow the existing style and formatting conventions used in the rest of the documentation. This includes heading styles, code block formatting, and emphasis.

Proofread Your Work: Check for spelling and grammar errors before submitting. Reading your text aloud can help identify awkward phrasing or mistakes.

By following these guidelines, you'll help maintain a high standard of quality in our documentation, making it a valuable resource for everyone involved in the project.