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.