Skip to content

Writing Guidelines and the Styleguide

Formalities

Folder and File Structure

  • There is no need in index files, as they will not be recognised as the landing page.
  • The file order is determined by their numeric order (see naming pattern).
  • Keep one topic per page; link related topics instead of mixing.

Naming pattern and order

  • Filename: Give files clear and descriptive titles (e.g., “Hetzner Dedicated Server Setup”).
  • Include the desired sequence number in the name of the folder or file; separate by underscore, "_".
  • Folder name structure: sequenceNumber_FolderTitle. Capital letters should be used with folders to achieve correct folder naming in the output. Example: 9_Documentation produces "9 Documentation" in the output.
  • Use lowercase with filenames: 03_mkdocs_build.
  • Connect name parts with underscores, "_".

Formatting for MkDocs

  • Use consistent headings (H2 for sections, H3 for subsections).

Visual aid

  • Use diagrams to visualise your input.
  • The app of choice for creating diagrams is MS Whiteboard. Whiteboard can be accessed from the SharePoint App Launcher: img.png
  • Store your diagrams in a place accessible to your colleagues to enable other people to edit and maintain the documentation - this is team work!
  • To keep the maintenance simple, store links to the diagrams, not jpgs or pngs.

Best practices

Template: Use the provided 03_template.md. Metadata: Include metadata (tags, keywords) for searchability. Code: Provide code snippets in fenced blocks with language tags. Navigation: No need for adding navigation anchors - automatic TOC at the top.

Changelog

Date Author Message
2026-03-04 aresnikowa QC-47927: aligned with the template, mkDocs formatting alignment
2026-02-25 aresnikowa Merge remote-tracking branch 'origin/master'