Help:Editor's Guide

Welcome to the wiki.bwhpc.de contributor guide. This document outlines structural rules, content principles, and syntax conventions to keep our HPC documentation accurate, maintainable, user-focused, and machine-readable across all bwHPC sites.

Editorial Meetings

Don't be an anonymous editor, join the meeting of bwHPC wiki editors. More information in our project gitlab page at https://gitlab.kit.edu/groups/kit/bwhpc-s5/-/wikis/Home/AP1.1/Redaktionsteam_bwHPC-Wiki

General Principles

Think from the User's Perspective

Goal-Oriented Writing

Always ask:

→"What is the user trying to accomplish?" Provide actionable commands, job submission scripts, and practical examples.

Avoid Technical Jargon Overload

→ Assume the user is an expert in their scientific domain (e.g., chemistry, physics), but potentially a beginner in HPC and Linux environments.

No Empty Placeholders

Do not publish empty pages or sections containing only headers with text like "TBD", "Work in Progress", or "Under Construction". If a page has no actionable information yet, keep it in a local draft or sandbox space until it provides immediate value.

But: Stubs are Welcome: Short pages or sections (stubs) that provide meaningful information are fine - our goal is to provide information not to create long texts.

Text Longevity

Avoid hardcoding very short-lived data that is bound to be outdated soon.

When documenting forseeably quickly aging things like a specific software version, explicitly state the version in your documentation so that outdated information does not become incorrect information when seen in the context of more recent versions.

Central vs. Local Scoping

┌─────────────────────────────────────────────────────────────┐
│               Generic / Cross-Cluster Content               │
│    (Slurm fundamentals, general module usage, scaling)      │
└──────────────────────────────┬──────────────────────────────┘
                               │
            ┌──────────────────┴──────────────────┐
            ▼                                     ▼
┌───────────────────────┐             ┌───────────────────────┐
│ Cluster-Specific Page │             │ Cluster-Specific Page │
│  (e.g., /Justus2/...) │             │  (e.g., /Helix/...)   │
└───────────────────────┘             └───────────────────────┘

1. Generic Content (Main Namespace):
   • Applies to all or most bwHPC clusters (e.g., workflow concepts, general environment module syntax).
   • Keep it independent of site-specific configurations.
2. Cluster-Specific Content (Subfolders / Subpages):
   • Applies only to a specific cluster environment (e.g., local storage paths, specific hardware queues/partitions, cluster hostnames).
   • Rule: Always place cluster-bound content under its respective subfolder:
     • Cluster_Name/Topic (e.g., Justus3/Storage, BinAC2/Partitions).

Syntax & Formatting

• Use the simpler Wiki Syntax whenever possible instead of reverting to HTML

• Keep Output Relevant: Do not paste raw console dumps or directory listings, but only document the command to list them on-cluster (examples are of course ok)
• Variable Syntax: Use standard angle brackets <placeholder> for user-defined parameters to clearly distinguish them from literal strings:
  • squeue -u <username>

• Use emphasis sparingly and on point. Writing something in bold is very often not as useful as you may think

• Internal vs External Links: Whenever something is in the wiki, an internal link, e.g. Registration should be used. The single brackets are for external links only.

Lifecycle Management & Verification

Articles should not stay unverified for longer than half a year. The wiki editorial team will coordinate the effort of reviewing pages. Pages kept to retain historic information must have a tag {{History}}