Skip to main content

Howto: SAGE Documentation

Authors
  • Kai Berszin
Last Updated10/12/2025, 12:48:54 PM
Last AuthorKai Berszin

Scope​

This document describes the process of writing documentation using the SAGE Documentation Wiki.

Introduction​

The SAGE Documentations utilizes docusarus to generate a user navigable website from static Markdown files.

Structure​

Hierarchy​

The documentation is structured in a hierarchical manner.

Each hierarchical level has one or more responsibles assigned.
These responsibles may deligate responsibility for children of their hierachy level.

A children of a hierachy level might be

  • A documentation page (markdown file)
  • A sub-hierachy (folder)

The responsibility of a sub-hierachy may be delegated further.

note

Before creating a new page or sub-hierachy, please consult the responsibles for the given hierachy level.

Hierarchy in practice​

In pratice each hierachy level is represented by a subfolder in the docs/ folder. Each hierachy level is required to have a document with the same name as the folder, describing the structure of the sub-hierachy and defining the responsibles, etc.

Embedded content such as graphics might be places in a folder called asset/. This fodler does not present a sub-hierachy.

Top level hierarchy​

On the top level we differentiate between

  • Engineering
  • Management
  • Mission
  • System
  • Testing

more information regarding the this structure can be found in the high-level Overview.

Editing pages​

As every page is just a simple file in the sage-documentation github repository, editing or creating a new page is as simple as editing or creating a file in the docs/ folder.

This can be done in various ways, the most common two are presented as follows:

Cloning the git repository​

By cloning the git repository from GitHub one can utilize any local text editor to edit pages.
Recommended is VSCode as it natively includes support for Markdown as also allows for an instant side-by-side preview of the written documentation.

Editing online in GitHub​

Instead of cloning the site locally one can also opt to use the online markdown editor provided by GitHub.
For this each page displays a Edit this page button on the bottom left of the page.

Be wary of simoustanly a single page at the same time as a different users.

If not explicitly knowing what you are doing, only a single user should edit a single page at the same time as merge conflics might arise.
If you have multiple users responsible for the page and are not versed with git, please ask beforehand.

Markdown​

Markdown is a lightweight markup language used for formatting text with simple syntax, making it easy to write and read. It allows users to add headings, lists, links, and other elements without needing complex HTML or rich text editors.

A cheat-sheet to markdown is given in in the cheat-sheet page.