Contributing

We want to welcome and include as many contributions as possible. All edits from small typos and grammar corrections to larger undertakings of guides and how-tos can be submitted and reviewed.

Ideally all articles should adhere to our guidelines. The aim is to bring them up to a standard that makes them more accessible for more users. Having said that, we will try to take all contributions bringing them up to standard where necessary.

If you plan to create something larger, please consider speaking to either staff or someone on IRC first. They might be able to help fit your work into the bigger picture.

The Wiki is stored in Git as HTML. It can be found on BitBucket.

If in doubt, check the source of other articles for examples.

Guidelines

All articles must:

HTML Formatting

The Wiki is written in HTML5 without inline CSS nor JavaScript. This means content should stick closely to the site's style. Below are the intended usage of elements:

<p>
Paragraph. Most prose should be placed in a paragraph container.
class="full"
Most elements attempt to be more readable by default and therefore have a width. This class will remove the width. Useful when a page element should use all available space i.e., non-text.
class="nontext"
Removes text-justification if applied to an element. Useful for non-text.
<ul, ol, li>
Lists should be used to separate content (making it more readable). Automatic indentation and bullet points.
<dl, dt, dd>
Definition lists. Useful for a list of key, value relationships with no row-based presentational structure.
<dl class="kv">
Makes the definition-list more dense for better displaying of key / values on a single line.
class="no-margin"
Remove left-hand indententation (useful on lists).
<table, tbody, tr, td>
Tabular data. Useful for presenting rows of data with options. Not to be used for formatting.
<thead, tfoot, th>
Column header and footer for a table. Both thead and tfoot should appear before tbody.
<h1>
Main article header. There should only be one occurrence.
<h2, h3, h4, h5, h6>
Hierarchical Headers for article sections. Each nested header belongs as a sub-group to the parent.
<pre>
Pre-formatted block-level (mult-line) text.
<blockquote>
Similar to pre: multi-line output quoting something someone has said.
<code>
Put around computer code. Surround in a pre block if mult-line.
<samp>
Inline "sample output" e.g., the result of a computer program or useful for single-line quotes. Surround in a pre or blockquote if multi-line.
<kbd>
Inline, user with commands and other user input. Surround in a pre or blockquote if multi-line.
<var>
Represents a variable. Intended for variables that wouldn't be handled as-is i.e. that the user is expected to change first.
<em>, class="emphasis"
Emphasise a word or short phrase.
<strong>
Strong emphasis. em is preferred and strong should be used sparingly.
<sup, sub>
<small>, class="small"
Inline aside element. Useful for an inline "Note: ..." .
class="quiet"
Reduces contrast on text. Useful for when a page element is required but not used most of the time.
class="dense"
Condenses text by reducing line-height.
<!-- ... -->
HTML comments must not be used under any circumstances.

Extravagant mark-up should be avoided and articles should be kept mostly to prose.

Target Audience

All articles should keep in mind the technical level of the target audience. This helps to keep explanations and assumptions suitable. Below are relevant target audiences:

Linux sysadmin
Happiest in a headless environment. Has probably memorised too many --options. Only wants a brief explanation on why obscure options are used (and even then, only whether to work out if pulling up the manpage is worthwhile). Looking for brief, concise overview of why something is being done. Will likely look up unknown options, tools, concepts on their own.
Power user
Probably runs Linux (intentionally) somewhere in his / her home. Knows the basics utiltiies and options, is eager to know more and wishes for explanations on commands and options as well as the general overview.
SSH user
Is running software as a means to an end. He / she is looking for a specific action "install x", "restart y" and so forth. Happy to dive into a little bit of the unknown to get something done i.e., copy and pasting provided SSH commands.
User
Would prefer not to have to install any extra software (beyond an SFTP client). Wishes for all actions to be done via a web interface on the website.

Picking a Target Audience

Articles under the same category should mostly have similar target audiences. The audience will be appropriate for the category. Most getting started guides should fall under "User" with enough explanations to cover the assumptions (e.g., so an "SSH user" article can simply say SSH into the slot).

There should be very few articles (if any) directed at the "Linux sysadmin" audience e.g., only someone with a lot of prior knowledge will understand it easily. These articles are likely contributions from individuals who don't know about these guidelines and hasn't yet been cleaned up.

General Standards

All articles must:

  • Have correct spelling and grammar:

    • both UK and US spellings are acceptable,
    • pages should be consistent in their choice,
    • and by nature of the business, UK spelling is preferred.
  • Have an introduction clearly stating the target audience.
  • State a clear goal in the introduction.

  • Fit into the Wiki hierarchical structure with the intention that the article can be found:

    • top-down by visiting from starting index by fitting into an existing category or sub-dividing an older one,
    • and side-to-side by being referenced by other links meaning the URL does not change.
  • Use hyperlinks as the engine of state (HATEOS). This means the article should use lots of links to necessary requirements ideally in the introduction so that the reader knows what is required beforehand.

  • Not repeat itself (DRY):

    • Another article should be linked instead of repeating its content.
    • If linking inside an article (instead of the whole page) then consider moving that content to a separate article.

  • Be self-contained. Which means:

    • All supporting files (especially images and scripts) must be stored in the Wiki repository itself alongside the article's HTML.
    • These supplemental files must be served via the same mechanism as the Wiki (i.e., don't use an external host).
    • Supplemental files should be stored in a folder next to the .html file. e.g., this article can be found at src/wiki/contributing.html so a related image would be placed into src/wiki/contributing/related.png.
    • Extra files that are not necessarily served may also be stored in this folder. This might include source code, originals or even notes arriving at the conclusions in the article. They should be removed once no longer relevant.
  • Lossless formats are preferred over lossy e.g., PNG over JPG.
  • Be timeless e.g., not attribute or thank specific individuals for contributing and try not to reference specific events.
  • Scripts should be non-interactive i.e., command-line options only.
  • If uncertain around standards, an article should endeavour to be consistent.

Category Standards

TODO (the following are notes):

  • API + server URLs are the same so we're locked into our first choice of URL once an article is linked. Find another method?
  • The first aim is to prepare for software articles (install, use, extra actions) with all having an "SSH user" target audience.

  • Therefore first categories should probably be:

    • Getting started (understanding the slot, site) @ user
    • Articles to be an "SSH user" e.g., getting to grips with SSH @ user
    • Software @ SSH user
    • Wiki @ HTML user (err, another type of user)
  • How would existing FAQ pages fit into this?
  • Should go through old FAQ plans.