Wiki style guide

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 bqueues to see the available queues", encode the command like this: <tt>bqueues</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 ~]$ bqueues
QUEUE_NAME      PRIO STATUS          MAX JL/U JL/P JL/H NJOBS  PEND   RUN  SUSP 
system           99  Open:Active       -    -    -    -     0     0     0     0
clc              94  Open:Active     256    -    -    -     0     0     0     0
bigmem.4h        88  Open:Active       -    -    -    -   745   720    25     0
bigmem.24h       86  Open:Active       -    -    -    -  3489  3160   329     0
bigmem.120h      84  Open:Active       -  960    -    -   320     0   320     0
bigmem.fair      80  Closed:Inact      -    -    -    -     0     0     0     0
normal.4h        68  Open:Active       -    -    -    - 22964 18362  4602     0
normal.24h       66  Open:Active       -    -    -    - 54744 44310 10434     0
normal.120h      64  Open:Active       - 1440    -    - 12686  5687  6999     0
normal.30d       62  Open:Active       -    -    -    -   304   295     9     0
normal.fair      60  Closed:Inact      -    -    -    -     0     0     0     0
virtual.40d      58  Open:Active       -    -    -    -     0     0     0     0
filler.40d       11  Closed:Active     -    -    -    -     0     0     0     0
light.5d         10  Open:Active       -    -    -    -     0     0     0     0
purgatory         1  Open:Inact        -    -    -    -     0     0     0     0

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