K Siegmund: to talk page

2026-10-07T14:55:38Z

to talk page

← Older revision		Revision as of 16:55, 7 October 2026
Line 70:		Line 70:

	* Internal vs External Links: Whenever something is in the wiki, an internal link, e.g. <code>[[Registration]]</code> should be used. The single brackets are for external links only.		* Internal vs External Links: Whenever something is in the wiki, an internal link, e.g. <code>[[Registration]]</code> 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 <code><nowiki>{{History}}</nowiki></code>

K Siegmund at 14:39, 6 October 2026

2026-10-06T14:39:52Z

← Older revision		Revision as of 16:39, 6 October 2026
Line 7:		Line 7:
	== General Principles ==		== General Principles ==

			=== Keep in Line General Wikipedia Rules as Applicable ===
	=== Think from the User's Perspective ===

			Many of Wikepedia's guidelines are very helpful for writing here as well, while some are specific to creating an encyclopedia.

			See e.g. https://en.wikipedia.org/wiki/Wikipedia:Writing_better_articles

	=== Think from the User's Perspective ===		=== Think from the User's Perspective ===

K Siegmund: /* General Principles */

2026-10-06T14:35:38Z

General Principles

← Older revision		Revision as of 16:35, 6 October 2026
Line 9:		Line 9:
	=== Think from the User's Perspective ===		=== Think from the User's Perspective ===

			=== 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.

		⚫	; Goal-Oriented Writing
⚫	; Avoid Technical Jargon Overload:
			: Always ask: ''"What is the user trying to accomplish?"''
⚫	: ~~→~~ Assume the user is an expert in their scientific domain (e.g., chemistry, physics), but potentially a beginner in HPC and Linux environments.
		⚫	: → 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.
			: → prefer common words over jargon, and if unavoidable, link jargon words to the [[HPC_Glossary]]

	=== No Empty Placeholders ===		=== No Empty Placeholders ===

K Siegmund: Created page with "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/Redaktionste..."

2026-10-06T14:31:46Z

Created page with "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/Redaktionste..."

New page

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 ===

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

# 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.
# 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:
#** <code>Cluster_Name/Topic</code> (e.g., <code>Justus3/Storage</code>, <code>BinAC2/Partitions</code>).

== 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 <code><placeholder></code> for user-defined parameters to clearly distinguish them from literal strings:
** <code>squeue -u <username></code>

* 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. <code>[[Registration]]</code> 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 <code><nowiki>{{History}}</nowiki></code>

Help:Editor's Guide - Revision history

K Siegmund: to talk page

K Siegmund at 14:39, 6 October 2026

K Siegmund: /* General Principles */