Documentation Style Guide#

Standards for writing clear, consistent, and accessible documentation.

This guide defines the documentation standards for the SKA Developer Portal. Follow these guidelines when creating or updating content.

Content Organisation#

Diataxis Framework#

Organise documentation using the Diataxis framework:

Type	Purpose	Example
Tutorial	Learning-oriented. Walk through a complete workflow step by step.	“Tutorial: Set Up Your Development Environment”
How-to	Task-oriented. Solve a specific problem or complete a task.	“How to Create a Merge Request”
Reference	Information-oriented. Provide facts, specifications, and lists.	“CI/CD Pipeline Variables Reference”
Explanation	Understanding-oriented. Explain concepts and background.	“How Containers Work”

Each tool or section contains up to four pages (one per Diataxis quadrant) plus a landing page with navigation cards.

Page Structure#

Every secondary page includes:

Hero section — Brief description of page purpose
Left sidebar — Section navigation
Right sidebar — “On this page” links to headings
See Also section — Links to related pages

Writing Style#

Use Active Voice#

Write direct, clear instructions using active voice.

❌ Avoid	✅ Use
“The file should be saved…”	“Save the file…”
“You should run the tests…”	“Run the tests…”
“The configuration should be updated…”	“Update the configuration…”
“It is recommended that…”	“We recommend…” or just state the action

Key rule: Use “must” for requirements, not “should”.

Be Direct#

Start instructions with a verb: “Clone the repository”, “Run the command”
Avoid unnecessary words: “In order to” → “To”
Use “you” to address the reader directly

Inclusive Language#

Use gender-neutral pronouns: “you”, “we”, “they”
For individuals, use singular “they” or a role name
Example: “If a team member needs help, they can contact the System Team.”

Headings and Structure#

Heading Hierarchy#

Use one H1 (page title) per page. Structure content with H2 and H3 headings.

Use Thomas Cokelaer’s heading syntax:

**********
Page Title (H1)
**********

Section (H2)
============

Subsection (H3)
---------------

Sub-subsection (H4)
^^^^^^^^^^^^^^^^^^^

Keep headings concise and descriptive. Readers scan headings to find information.

Breadcrumbs#

Breadcrumbs are provided by the theme navigation. Do not add custom breadcrumb markup.

File and Folder Naming#

File Names#

Use hyphens, not underscores: contrib-guide.rst ✅ not contrib_guide.rst ❌
Keep names concise but descriptive
Prefix with Diataxis type for tool pages: tutorial-, howto-, reference-, explanation-

❌ Avoid	✅ Use
`thng.rst`	`contribution-guide.rst`
`development_guidelines_and_policies.rst`	`dev-guidelines.rst`
`container_stuff.rst`	`howto-container-tasks.rst`

Folder Structure#

Each tool section follows this structure:

tools/
└── tool-name/
    ├── index.rst                    # Landing page
    ├── tutorial-tool-name.rst       # Tutorial
    ├── howto-tool-tasks.rst         # How-to
    ├── reference-tool-name.rst      # Reference
    └── explanation-tool-name.rst    # Explanation

Images and Media#

File Location#

Store images in an images/ directory alongside the .rst file:

contributor/
├── images/
│   ├── edit-on-gl.png
│   └── view-app.png
└── howto-contribute-portal.rst

Image Naming#

Use the same naming conventions as .rst files: lowercase, hyphens, descriptive.

Alt Text#

All images must have alt text for accessibility:

.. image:: images/edit-on-gl.png
   :alt: The Edit on GitLab link in the top right of a Developer Portal page.

Write alt text that describes the image’s purpose, not just its appearance. If a figure caption provides the same information, alt text can be omitted.

Contrast#

Ensure images have adequate contrast. Test by previewing in black and white — if still legible, contrast is acceptable for users with low vision.

Links and Cross-References#

Internal Links#

Use :doc: for links within the Developer Portal:

See :doc:`/tools/git` for more information.

This allows Sphinx to detect broken links. Do not use URL syntax for internal pages.

External Links#

Use standard reStructuredText link syntax:

Visit the `SKAO website <https://www.skao.int>`_ for more information.

Reference Labels#

For linking to specific sections, add a label above the heading:

.. _branching-policy:

Branching Policy
================

Then link to it:

Follow the :ref:`branching-policy`.

Code Examples#

Use code blocks with language hints for syntax highlighting:

.. code-block:: bash

   git clone --recurse-submodules git@gitlab.com:ska-telescope/project.git

For inline code, use double backticks:

Run ``poetry install`` to install dependencies.

Keep code examples minimal and focused. Include only what’s necessary to illustrate the point.

SKAO Brand#

Colours#

The Developer Portal uses SKAO brand colours:

Colour	Hex	Usage
Navy	`#0c1445`	Primary background
Magenta	`#e91e8c`	Accent, links, highlights
Text Primary	`#f0f4ff`	Main text on dark backgrounds
Text Secondary	`#a8b4d4`	Supporting text

Typography#

The portal uses IBM Plex Sans for body text and IBM Plex Mono for code.

Quick Reference Checklist#

Before submitting documentation:

☐	Active voice used throughout (no “should”, use “must” for requirements)
☐	One H1 per page, logical heading hierarchy
☐	Breadcrumbs included for secondary pages
☐	File names use hyphens, not underscores
☐	All images have alt text
☐	Internal links use `:doc:` syntax
☐	Code blocks have language specified
☐	Content organised by Diataxis type where applicable