Wiki style guide

From ScientificComputing
Revision as of 09:15, 30 June 2023 by Lhausammann (talk | contribs) (Commands and shell output)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This article provides styling guidelines for the contents of the SciComp wiki.

Structure

Keep the structure of a page clean, simple and well balanced. In principle an article should not have more than 4 levels. The page title is level 1 and the current section is level 2

Level 3

This is an example of level 3...

Level 4

... and of level 4.

Level 5

As you can see, things become messy down here because level 5 is hard to distinguish from level 4. As a consequence, level 5 should be avoided at all cost.

If a part of an article is much more complicated than the rest, then perhaps you should consider moving it into a wiki page of its own.


Voice

Avoid the 3rd person and the passive voice. Consider:

  • BAD: ssh must be used to access the cluster, and authentication must be done using ETH username and password
  • BAD: one must use ssh to access the cluster, and authenticate oneself using one's ETH username and password
  • BAD: users must use ssh to access the cluster, and authenticate themselves using their ETH username and password
  • GOOD: please use ssh to access the cluster, and authenticate using your ETH username and password

Of course, there are cases where a passive form is better. Use your best judgement.

Commands and shell output

When citing commands in a sentence, such as "use squeue to see the available queues", encode the command like this: <tt>squeue</tt>.

When showing a command and its output in a code section, make the command(s) stand out using bold characters, e.g.:

[leonhard@euler06 ~]$ squeue
JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)

For the prompt, always use user leonhard. If a prompt on a local computer is required, use leonhard@calculus.