Help:Writing wiki articles

From bwHPC Wiki
Jump to navigation Jump to search

This page gives some general guidelines and some tipps on how to write on a page

Always Create "Finished" Pages

Even when a page is missing content, don't leave empty headings and placeholders on the page. If you think you must have outlines to keep your thoughts on track, you can either use html comments to hide unfinished things <--! hidden text > or you can create the page as a sub-page of your user page.

No Volatile Content

Information that changes often has no place in the wiki, specially if a current version of the information can be obtained on the cluster system at any time.

Document how the user can get the information on the cluster, not the information itself.

Don't Write HTML

Use wiki-syntax whereever possible. I.e. not html links with single square brackets for wiki-internal pages or html formatting where wiki formatting does the same thing but stays readable. See https://de.wikipedia.org/wiki/Hilfe:Wikisyntax (German) and on formatting specifically https://www.mediawiki.org/wiki/Help:Formatting

Use Text Formatting Sparingly

Emphasis of certain text parts loses its power when used too much. You may think something is especially important - but at some point everything in the wiki is important to someone at some point, else there would be no need to put it into the wiki.

Consider the User Perspective

When writing content, have in mind that there will always new users. Avoid Jargon wherever possible, specially in the titles of articles, as that will make finding the relevant wiki page difficult. If the term is useful for more experienced users, use the term or its explanation in parenthesis.