Skip to content

Contribute to the Switch Cloud Documentation

The Switch Cloud Documentation provides users with the essential knowledge and guidance to work with our cloud services. Keeping our documentation accurate and well-maintained is essential – it helps users work more efficiently with our services and reduces their need for direct support. While each team is responsible for their service-specific content, we follow shared guidelines to maintain consistency throughout the documentation.

The following guidelines outline how to add or update documentation while maintaining consistent formatting and styling across our content.

Documentation Directory Structure

Each page in our documentation is represented by a directory (page bundle) containing an index.md file and its related resources directly in the directory. Sub-pages are represented by sub-directories following the same structure.

Example Directory Structure 
documentation/ # Root directory
├── index.md
└── S3/ # Service page bundle
    ├── index.md # Main service documentation
    ├── versioning/ # Another sub-page bundle
    │   ├── index.md
    │   ├── managing-versions-in-scs3/ # Sub-sub-page bundle
    │   │   ├── index.md
    │   │   └── example-flow.png # Image in sub-sub-page bundle
    │   └── .navigation.yml
    ├── create-S3-bucket/ # Sub-page bundle
    │   ├── index.md # Sub-page documentation
    │   ├── s3-image.png # Image in sub-page bundle
    │   └── create-bucket-diagram.drawio.svg # Diagram in sub-page
    └── .navigation.yml
  1. Bundle Structure Each page is a directory containing:
    • index.md (page content of bundle).
    • All related resources directly in the directory.
    • Sub-directories for sub-pages (following the same structure).
  2. Naming Conventions
    • Use kebab-case for directories and files.
    • Descriptive names reflecting content.
    • Page bundle (directory) names appear in navigation.
  3. Resource Management
    • Place all assets (images, diagrams, tables, and similar items) directly in the page bundle where they are used.
    • Shared assets go in the common parent page bundle.
    • Use meaningful filenames that describe the content.
    • Clean up unused assets.
  4. Sub-page Organization
    • Create sub-page bundles for logical content grouping.
    • Maintain the same structure in sub-bundles.
    • Maximum 3 levels deep recommended (service -> group -> pages).
    • Parent directories should contain a .navigation.yml to define page titles and order.

Language Guide

Switch Cloud documentation should be clear, concise and easy to understand.

Use:

  • British English with British grammar and spelling.
  • Standard text for links.
  • Lists and tables instead of complex sentences and paragraphs.
  • Common abbreviations like AI and CI/CD and abbreviations you've previously spelled out.
  • Active voice instead of passive.

Avoid:

  • Unnecessary words.
  • Phrases that hide the subject like there is and there are.
  • Ambiguous pronouns like it.
  • Latin abbreviations like e.g. and i.e..
  • Contractions when used with proper nouns (Terraform's a tool → Terraform is a tool), in negative emphasis (Don't install → Do not install), or error messages (aren't allowed → are not allowed).
  • Possessives ('s) for proper nouns, like organisation or product names, for example instead of 'Docker's CLI', use 'the Docker CLI'.

Keep the following in mind:

  • Be consistent with feature names and how to interact with them, without the addition of sales or marketing text.
  • Format dates and times consistently and for an international audience.
  • Use images, including screenshots, sparingly.
  • Try to write from a customer perspective and to speak directly to the user.

Style Guide

Titles

Formating

  • Write action-oriented titles using imperative verbs to clearly indicate the task, for example, "Create a Private Network" or "Deploy a Virtual Machine."
  • Prefer title case, i.e. capitalize the first, last, and major words, e.g. "Manage User Permissions", do not capitalize articles, conjunctions, or prepositions unless they are the first or last word.

Levels

  • Each documentation page begins with a level 1 title (#) and there should be only one level 1 (H1) title per page.
  • For each subtopic, increment the title level, which means increment the number of # characters in front of the topic title.
  • Avoid title levels greater than #####. Title levels greater than H5 do not display in the page contents.
  • Do not skip a level. For example: ## > ####.

Text Formatting

Quotation Marks

Always use neutral quotation marks (', ") instead of the typographic equivalent (‚, ‘, ’,„, “, ”, «, »). For example, use it's instead of it’s.

Bold

Use Bold for all UI elements and navigation paths. To make text bold, wrap it with double asterisks (**).

For example:

Navigate to **Project > Volumes > Volumes** and click **Create Volume**.

Avoid using Bold for emphasis. Instead, use admonitions or structure the documentation to eliminate the need for text emphasis.

Inline Code

Use Inline code for:

  • Text a user enters in the UI.
  • Short inputs and outputs like true, false, Job succeeded, and similar.
  • Filenames, configuration parameters, keywords, and code. For example: .gitlab-ci.yml, --version, or rules:.
  • Short error messages.
  • API and HTTP methods (POST).
  • HTTP status codes. Full (404 File Not Found) and abbreviated (404).

Τo use inline code, wrap the text in single backticks (`). For example:

In the **Name** text box, enter `test`.

Code Blocks

Use Code blocks for command line examples, and multi-line inputs, outputs, code, and similar.

To add a code block, add triple backticks (```) above and below the text, and specify the language for proper syntax highlighting.

For example:

```sh
openstack server create --flavor c001r002 --image Ubuntu-22.04 (Switch Cloud) --nicnet-id=<network_id>\
--key-name <key_name> --user-data ./dbserver-user-data.yaml\
<instance_name>
```

Placeholders

Write placeholder variables in lowercase and separated by underscores to improve readability and consistency.

For example:

openstack volume show <volume_id>

Lists

Use lists to organise information in a format that is easier to read and comprehend.

  • Use dashes (-) for unordered lists.
  • Start items in an ordered list with the respective number, for example 1., 2., and so on.
  • Leave a blank line before and after a list.
  • Start all items with a capital letter.
  • Nest an item under a list item, using a 4 spaces indentation (MkDocs syntax), to maintain alignment.

For example, the following list with nested items:

- List item 1
    A line nested using 4 spaces to align with the `L` above.

- List item 2

    ```text
    a code block that nests inside list item 2
    ```

- List item 3:
      - Nested list item 1.
      - Nested list item 2.

renders as follows:

  • List item 1 A line nested using 4 spaces to align with the L above.

  • List item 2

    a code block that nests inside list item 2

  • List item 3:

    • Nested list item 1.
    • Nested list item 2.

Tables

Tables should be used for data that's best described by a matrix.

  • To create a table in the text, use the following format:
| Name     | vCPUs | RAM  |
|----------|-------|------|
| c001r001 | 1     | 1 GB |
| c001r002 | 1     | 2 GB |
| c001r004 | 1     | 4 GB |

which renders as follows:

Name vCPUs RAM
c001r001 1 1 GB
c001r002 1 2 GB
c001r004 1 4 GB
  • To create tables for a cli command output use the following format:
+--------+----------+--------+------+-----------+-------+-----------+
| ID     | Name     |    RAM | Disk | Ephemeral | VCPUs | Is Public |
+--------+----------+--------+------+-----------+-------+-----------+
| 001001 | c001r001 |   1024 |    0 |         0 |     1 | True      |
| 001002 | c001r002 |   2048 |    0 |         0 |     1 | True      |
| 001004 | c001r004 |   4096 |    0 |         0 |     1 | True      |
+--------+----------+--------+------+-----------+-------+-----------+
  • Add additional spaces to make the column widths consistent, except in the rightmost column for tables that are very wide.
  • Try not to leave any empty cells, instead consider entering N/A for "not applicable" or None.
  • To link to another .md file in the same documentation, use an inline link with a relative file path. For example, [Start a Linux-based Instance](compute/compute-quick-start/start-a-linux-based-instance.md) that renders as Start a Linux-based Instance.
  • Each topic title has an anchor link. For example, a topic with the title ## This is an Example has the anchor #this-is-an-example.
  • Use descriptive text for links, rather than words like here or this page.
  • Try to avoid links to external documentation, because they easily become outdated, and are difficult to maintain.

Admonitions

Use admonitions (alert boxes) to highlight important information, warnings, or examples. Keep admonition content concise and focused on a single point.

Important Info

Use the following syntax for important info:

!!! info "Important"

    The instance name must be unique within the project.

renders as follows:

Important

The instance name must be unique within the project.

Important info admonitions should be used for important information that users should be aware of. The title can be replaced if necessary with something more indicative to the case.

Warning

Use the following syntax for a warning:

!!! warning "Caution"

    Deleting an instance permanently removes all data associated with it.

renders as follows:

Caution

Deleting an instance permanently removes all data associated with it.

Use warning admonitions for critical information or potential issues. A custom title that draws attention can be used.

Example Output

Use the following syntax for an example output:

````md

Example Output

text +--------+----------+--------+ | ID | Name | Status | +--------+----------+--------+ | 001001 | c001r001 | ACTIVE | +--------+----------+--------+

```

renders as follows:

Example Output

```text +--------+----------+--------+ | ID | Name | Status | +--------+----------+--------+ | 001001 | c001r001 | ACTIVE | +--------+----------+--------+

```

Use output admonitions for CLI command outputs or examples that can be collapsed to save space. The title can be adjusted accordingly.

Tabs in Documentation

Tabs are used to present different methods of achieving the same task, such as showing both UI and CLI instructions. Any relevant code blocks, lists, or admonitions should be included within the tab's content using 4-space indentation. Tab names should be kept short and descriptive, for example:

  • Horizon Dashboard / OpenStack CLI
  • Linux / Windows / MacOS
  • Python / C#

Use the following syntax for tabs:

```md

Navigate to Project > Compute > Images to view your images.

  1. Click the image name
  2. Select Edit from the actions menu

List all images:

sh openstack image list

Show image details:

sh openstack image show <image_id>

```

that renders as:

Navigate to Project > Compute > Images to view your images.

  1. Click the image name
  2. Select Edit from the actions menu

List all images:

sh openstack image list

Show image details:

sh openstack image show <image_id>

Caution

Do not use headings (##, ###, etc.) inside tab content. Headings within tabs do not integrate properly with the navigation ToC on the right side. Users navigating to these headings may experience broken links if they are not already on the correct tab. Instead, place your tabs under the main section headings.

Provide Client Configuration Documentation

All content owners should describe the supported tools for their respective services and provide the necessary configuration details and examples for different user actions.

For each service – S3, Kubernetes, and Compute – the documentation should include:

  • A clear mention of the supported tools (for example, OpenStack CLI, OpenTofu, kubectl, Rclone).
  • The required environment variables or configuration files needed to use these tools.
  • Example commands or scripts for performing key actions using the supported tools.