Difference between revisions of "Wiki style guide"
(Created page with "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...")
Revision as of 16:16, 4 August 2016
This article provides styling guidelines for the contents of the SciComp wiki.
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
This is an example of level 3...
... and of level 4.
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.
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.