Skip to content

How to write and update these docs

These docs explain what RIQS does, who can do what, and how to do it, in plain language. Anyone should be able to read a page and understand it: a new team member, a tester, a product owner, or a client.

Writing rules

  1. Plain English. Short sentences. One idea per sentence. Explain any special word the first time you use it, or link to the Glossary.
  2. Write for the user, not the code. Say "Click Save", not "the form calls the save mutation". Do not mention repositories, code, APIs, database names, or ticket numbers.
  3. Use the names the user sees on screen. Write button and menu names in bold, exactly as shown in the app.
  4. Use tables for "who can do what" and numbered steps for "how to do it".
  5. Be honest. If something is planned and not built yet, say so. If behaviour is unclear, add it to the "Open questions" section at the bottom of the page, not as a guess in the main text.
  6. Keep pages short. If a page grows past what a person can read in about 10 minutes, split it.
  7. Same layout everywhere. Every module page uses the template below, so readers always know where to look.

Where permissions come from

The Roles & Rights sheets (RIQS wiki, "Roles & Rights" pages) are the source of truth for who can do what. They win over the feature list when the two disagree.

The app does not always match them yet. Pages always describe the intended rule from the sheets. If the app behaves differently, do not write that on the page. Add it to App permission gaps (docs/internal/app-permission-gaps.md, in the repository only, never published) (internal fix list, not for clients).

Role names

Always use these names (see Roles & permissions):

RiQS Administrator · Group Administrator · Administrator · Power User · Management · Professional

Function roles (given on top of a role): CIRS Officer, Complaint Officer, Ideas Officer, Feedback Officer, Fault Officer, Hint Officer, Equipment Officer, RiQS-Pedia Officer, Auditor, Committee, Unit Manager, Organisation Manager.

"Unit" is the business word. In some places of the app a unit is also shown as a "Client". Always write "unit" and mention the other name only in the glossary.

Module page template

# <Module name>

> **In one sentence:** <what this module is for>.
> **Menu:** <where to find it in the left menu>  ·  **Status:** Live | In progress | Planned

## What it is
2–4 short paragraphs. What problem it solves, in everyday words. An everyday comparison helps.

## Key terms
| Term | Meaning |

## Who uses it
| Role | What they typically do here |

## How it works
The main flow, step by step, from start to finish (e.g. create → assign → do → review → report).
A simple flow line is welcome, e.g. `Draft → Published → Completed`.
Include the statuses an item can have and what moves it from one to the next.

## How to …
One sub-section per common task. Each one:
### How to <task>
**Who can do this:** <roles>
1. Step
2. Step
**Result:** what the user sees afterwards.

## Rules to know
Bullet list of business rules: limits, who gets notified, what happens on delete, approval rules, audit-safe mode, etc.

## Who can do what
Permission table: rows = actions, columns = the six roles (plus function roles where relevant).
Use ✅ allowed · ❌ not allowed · text for conditions (e.g. "own unit only").

## Connected modules
How this module uses or feeds other modules, with links.

## Open questions
Things that are not yet clear. Remove a line when it is answered.

Where things live

docs/
├── mkdocs.yml            # site settings and the left menu (nav)
├── content/              # every published page
│   ├── index.md          # Start here
│   ├── foundations/      # what RIQS is, org hierarchy, roles & permission model, glossary
│   ├── <module>/         # one folder per module, the module page is index.md
│   │   └── <topic>.md    # deeper pages of that module (e.g. configurator/control-task-templates.md)
│   ├── decisions/        # decision log
│   ├── how-to/           # index of all "How to" sections
│   ├── images/           # screenshots
│   └── assets/           # logo, riqs.css, riqs.js (site look)
├── internal/             # never published (e.g. app permission gaps)
└── scripts/              # screenshot script
design/                   # HTML design and prototypes (screens/, assets/)

Folder and file names are lowercase with hyphens, for example risk-management/index.md.

How to add a module

  1. Create the folder docs/content/<module>/ and the page index.md in it.
  2. Use the module page template above, with every section in the same order.
  3. Add a screenshot (see Screenshots) under the header box.
  4. Add the module to the left menu in docs/mkdocs.yml, in the right group.
  5. Add a row to All modules.
  6. Add its "How to" sections to the How-to index.
  7. Add new words to the Glossary.

How to add a page inside a module

Use this when one part of a module needs more room, for example one Configurator tab.

  1. Create docs/content/<module>/<topic>.md. Use the module page template.
  2. Add it under the module in docs/mkdocs.yml.
  3. Link it from the module page: under the matching "How to" section, and in Connected modules.

When the content is not ready yet

Do not leave a module, topic or business area out just because it is not written yet. Create the page so readers see that it exists:

# <Name>

> **Status:** Will be added later.

This page is reserved for **<name>**. The content will be added once the business rules are agreed.

_Last reviewed: <date>_

Add it to the menu like any other page. When the content is written, replace the whole page with the module page template.

Decisions

When the team agrees on a rule for RIQS or for these docs, add a row at the top of Decisions. Never delete a row; mark it Replaced by D-x instead.

Screenshots

  • Taken from the test system with the test accounts, never from a customer system.
  • Module screens show the Power User view. Administration screens show the Administrator view.
  • The script blurs email addresses and phone numbers. Check every image anyway before you commit it: the site can be opened by clients.
  • Save images in docs/content/images/ with the module name, e.g. risk-management.png.
  • Under each image, add one plain line: what the screen shows, ending with "Screens show test data."

How to change a page

  1. Edit the page in the same layout.
  2. Update the "Last reviewed" date at the bottom of the page.
  3. If a feature is new, also add it to All modules and the How-to index when needed.
  4. Open a pull request. When it is merged into main, the site is published automatically.