Difference between revisions of "Wiki style guide"

Revision as of 18:29, 4 August 2016

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 NETHZ username and password

• BAD: one must use ssh to access the cluster, and authenticate oneself using one's NETHZ username and password

• BAD: users must use ssh to access the cluster, and authenticate themselves using their NETHZ username and password

• GOOD: please use ssh to access the cluster, and authenticate using your NETHZ 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.:

% 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

Alternatively the command could be preceded by a full prompt, like:

[byrdeo@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
...

The short (anonymous) prompt is more portable and works for Brutus, Euler and Leonhard, whereas the full prompt is more realistic. We just have to decide which one we want to use.