Styling Rules for online documentation

When writing about Cumulus, it is difficult to avoid getting technical in places, but we should aim to make documentation as readable as possible. There area number of ways to measure readability - see https://www.wordcalc.com/readability/ for more information. There are also standards for computer documentation - see https://www.techscribe.co.uk/techw/standards.htm. The following guidance is written specifically for this Wiki and may help you to contribute in the best way possible.

Keep pages to a reasonable length
- Split documentation into separate pages whenever possible to identify break points
- It is possible to name Wiki pages hierarchically, for example this page is Editing, but its URL places it under the Help:Contents page, giving an option at the top of this page to move up hierarchy.
Within pages use short paragraphs or bullet points to aid readability
- Short sentences also aid readability, try to minimise use of "and", by either splitting sentence or expressing each clause as a numbered bullet point
- Use sections, and sub-sections, to make navigation to points of interest easier
- Place first in the page the most important information, so people don't need to read a lot to find it
- Use cross-references to other Wiki pages, or external pages (but remember you have no control over whether external pages remain available), to avoid needing to insert a lot of detail into original page
- If something is complicated to explain, try to break it up into a series of numbered steps
Assign pages to categories, a full list of existing categories can be seen at Special:Categories
- To add your page into a category, use chain link icon and type "Category:" into top box and you will see existing categories appear, as you type more, the list shrinks
- Only administrators can edit certain pages (like the "main page"), so linking to an existing category gives you link from "main page"
- You can of course create a new category page to which you will link multiple new pages, but it is best if that category page is in turn linked back to an existing category
- To add a link from your page giving your own text for somebody to follow to get to a category page, prefix that Category page name with a colon ("[[:Category: category_name|text_you_want]]".

Creating a new page

All Wiki page names always start with a capital letter, and the Wiki will always replace an initial lower case letter with the equivalent upper case letter. You can choose the case of subsequent letters, but these must always be specified in any references to the page exactly as when the page was created.

It is easier for the reader to find information on multiple short pages, than have to read a long page. Think carefully about page names; if you use a word like "New" in connection with a feature added in a particular release, will the contents remain "new" for evermore, or will they become "standard" when older releases are forgotten. In general, page names should be kept short, but if a topic is split over several pages, each page name must make it clear what is on that particular page.

The web page name you choose will form part of a URL https://cumuluswiki.org/a/'''new_page_name''', so it is normal to place underlines between words in a page name (because spaces cannot appear in a URL, and would be replaced by the messy "%20" code).

The simplest way to create a new page is to search for the topic. If there are no pages which satisfy you, then use the 'Create this Page' option (at the top of the search results page).

To create a new page, there are two other ways:

When you feel you have enough on the current page simply enclose the proposed name of the page in double square brackets [[.....]] in a cross-reference on your existing page.
- A link to an internal page name that does not exist, will appear in red on the existing page. Clicking that link will take you (or anyone else) to a new screen where you can create the new page.
Go to the URL box in your browser, and replace the name of any existing page (that you are reading, not editing) with your proposed new name, then go to the URL.
- A screen will appear saying that you have linked to a page that does not yet exist (or has exited before and been deleted), saying that if you type in content then the page will be created.

Be careful a reference to (for example) [[webTags]] would create a new page, as that capital T in the middle is different to the name of the existing Webtags page.

Templates

When you create a new page, you can reference templates that will add standard predetermined content to your page.

Type {{Template:WorkInProgressBanner}} to add a banner to that point in the page saying "Work In Progress". The coloured background makes this content stand out.
Type {{Template:Version badge Mx}} to put your page into Category: Cumulus MX and display a MX symbol.
(For legacy cumulus) type {{Version badge 1}} to put the page into Category: Cumulus 1 and display a "v1" symbol.

Other templates are available, and you can create a new template if there is a standard piece of text you want to be able to insert in multiple places.

Renaming and Redirect

If you are Registered and a logged-in user, and you see a typo in an existing page name, there is a Move tab (seen at top of page). This allows you to give a new name to that page. All history, related to old page, is moved to new page, as well as the page content, so nothing is lost.

"Move" could also be used if you think another page name would be be clearer, but it is best avoided on established pages, as links to the existing page may exist not only on other Wiki pages, but also in Cumulus Support Forum Posts.

You will see an option to create a redirect. For a standard logged-in user, it is recommended you don't select this. A redirect retains the old page, and the content of that old page includes a link that automatically redirects anyone selecting that old page to the new page (unless they get to the old page from the new page, in this exception you stay on old page).

If links to the old page exist, a standard logged-in user needs to manually edit each link individually. If redirect exists, the old links will get to the correct page by first opening the redirect page. If redirect does not exist, the old links will turn red, to indicate they now link to a non-existent page. A logged-in administrator can do a global edit, search for [[old-page-name and replace with' [[new-page-name.

Editing a page

Remember: In the Cumulus Wiki you can only edit/create pages if you are Registered and Logged in.

It is highly likely that typographical errors exist on pages, they can be edited by people who press the wrong key by mistake, on devices that supply irrelevant word suggestions, or are using a device with a small screen making it hard to be sure what was typed! Any contributor who corrects such errors is doing a highly appreciated task!

Cumulus development proceeds at such a pace that existing entries in this Wiki often become out of date. Any contributor who helps with bringing it up to date is also appreciated. However, you must remember not everyone uses the latest release, so be careful not to remove material relating to the original Cumulus for example, and consider creating a new page documenting the latest release.

If you wish to edit an existing page simply search for it and then click the 'Edit' tab at the top. If you are not logged in, you can "View source" to see what the page content looks like when typed into an editing screen.

You can "Compare Revisions" using the History tab (visible at top of page). That feature also allows you to revert to any previous edit, if you mess up a page by your edit. But we hope, you only do an edit to an established page, if you are confident with what you are doing.

Identify your updates to others

The Cumulus Wiki keeps a historic copy of every change on every page of the system.

Before you save your page, take a moment to complete the Summary box at the bottom and explain why you edited the page.
- It is best if this explanation is kept short, but is specific and will mean something to other people
- Examples: "Typo" or "Bringing up to date" or (if moving text to another page) "Cut"
If this is a minor edit, tick the box.
- A minor edit would typically be you fixing a typo, spelling error, or layout problem (e.g. number of equal signs does not match on each side of heading, or identifies wrong sub-level).
- Major edits are new content, splitting content between pages, updated content, etc.

We log who changed the page, and when, so your username will appear on the 'History' tab.

Editing Tips

You can optionally use "View Source" (if you are not logged in) or Edit the page (but do not save), click inside the text box, "Select All" and Copy the existing text into say "Libre Office writer" (or another external editor) and get your text right there, before you Paste it back, if you feel the need to do a massive edit that will take some time.
- Check someone else has not edited the page before you paste back!
Always Preview your work, refine, and preview again before saving.
- This avoids you having to do a further edit because of typos or layout errors.
- Don't over save as the system retains a history of every save. Save only when your article/edit is complete.
If you are not sure how to do something in WikiText, look at another page and 'View Source' (if you are not logged in) or Edit the page (but do not save) to see how someone else has formatted a page. (Tip - Open a second browser window)
Each user has their own user page to experiment in. Click on your name at the top of the screen and edit your own page.
A few of the pages on the Cumulus Wiki are protected and only editable by Administrators. For example, the main page, help, disclaimer, etc. The majority of pages are fully editable by registered users.

Further Help

Full and extensive help is available on the MediaWiki software page under Editing

Wiki formatting

When writing for a Wiki there are a number of formats you can write in. The most common, and preferred method, is Wiki Markup or WikiText. This is simply text with a variety of symbols to quickly produce consistent and navigable pages. In the following sections you will learn the basics of WikiText. This is a very powerful markup language however what is detailed below is a good starting point.

In addition to WikiText you can write part or all of the page in HTML, PHP, Javascript and a few other languages. Where ever possible use WikiText as it is the most efficient for delivery and formatting. After a few minutes of writing a page you will be familiar with the basics.

Plain text

This will be the bulk of your page and you simply type as you would read, with sentences, punctuation and paragraphs.

Formatting your text

Italics

Two apostrophes either side of your text will italicise it. Alternatively, click the slanted "I" icon.

Example: This should have the last word in ''italics''

Result: This should have the last word in italics

Bold

Three apostrophes either side of your text will make it bold. Alternatively, click the "B" icon.

Example: This should have the last word in '''bold'''

Result: This should have the last word in bold

Bold and Italics

If the two apostrophes for italics and the three apostrophes for bold are combined, making five apostrophes either side, will both bold and italicise the enclosed text.
Four apostrophes does nothing!

Underline

use the HTML markup for underline. <u> tag at the start and </u> at the end of your word of phrase.

New Paragraphs

If you simply press the Return key to end a line, then except in a list (with # or *), you will find the text you type appears as a continuation of the last line without a paragraph break.

You need to leave a blank line to make the next text be in a separate paragraph. Alternatively, to force a further paragraph, use the old HTML code of <br/>, at the end of the previous paragraph.

Creating Sections

If you are writing anything longer than a few paragraphs, there will be a good chance that it reads better if split into sections, and has a table of contents (as with this page).

If you split your page into sections, editing will be easier, as you can select to edit just one section (and any sub-sections), instead of using the Edit tab which shows the entire page in the editing window.

All you need do is mark your headings appropriately.
- Start your Section name on a new line, with one (or more) equals symbols on each side of your heading text.
- Use "View Source" tab at the top of this page, to see how this page uses sections and sub-sections
- Only those with administrative access can edit this page, so standard users do not see an "Edit" tab for this page
WikiText will then automatically create the sections, deal with all the formatting of headings, and make the page look good.
- If you create more than three sections, the Wiki will automatically generate a contents page just before your first heading.
- If you want some text to be seen before the table of contents, don't use a heading before that text.

To force creation of a table of contents on the right hand side of the page (so letting the reader see your introductory text before this) use {{TOCright}} as this page does.

Sections can be arranged in a hierarchical manner:

Top level section names will use a single equals sign each side of them
- The next level will have two equals signs each side of the heading
  - The third level will have three equals signs
    - The fourth level will have four equals signs each side of the heading

It is possible to go to lower levels, but more than 4 levels can look messy.

Sections will be numbered, with subsection numbers separated from section above number by a full stop.

A blank line before and after any heading line makes it easier to see the headings when editing the page, but do not affect the look for the reader.

Example....

=Weather Stats=

Normally, within the section, you add text in short paragraphs

Second paragraph

You can add lists as explained below.

==Historic Facts==
More text

Create sub-sections by using more equals signs.

Example....

==Weather Stats==

More text, and short paragraphs

===This Year===

this years data

===Last Year===

Last years data

==Historic Facts==

More text

Lists

Simple lists with bullets are produced by starting the paragraph with a * symbol.

Numbered lists start with a # signs (the Wiki then adds numbers, not you)

You can add further * or # symbols after the first to create indented further bullets or numbered sub-lists

Indent a paragraph by starting with a : symbol

Cross references to other Wiki pages

You may wish to refer the reader to information on other pages to further expand their knowledge or explain something in more detail. If you are referring to another page already in the Cumulus Wiki simply enclose the name of the page is two square brackets (just as advised above to link to a new page). If you wish to show a different word or phrase that will mean more to the reader, than the page name, use the | symbol after the page name and then type the phrase you want the reader to see (this latter approach is also used where you want to replace underlines in the page name with spaces to make it look better to the reader):

Examples: [[Webtags]] and [[Webtags|Cumulus web tags]]

In the first example, if the reader clicks on the word Webtags they will be taken to the page of the same name. In the second case, the user will see the words Cumulus web tags but when they click it will take them to the Webtags page. Be careful with the case of the page name when linking in Wiki. The case of the first letter does not matter, so linking to [[webtags]] or [[Webtags]] is the same as Wiki will always uppercase the first letter.

Remember, the case of all letters except the first does matter, and if you do not match the original page name, the Wiki will think you want to link to a page that does not yet exist.

Creating a link to an external page

if you wish to link to a page outside the Cumulus Wiki, such as a post on the support forum, enclose in one set of square brackets: the full URL, a space, and then a descriptive phrase.

Example: [http://www.google.com Google]

The reader will see the word Google but on clicking that they will be taken to an external page.

If you are happy for the URL to be seen, without descriptive text, then just type the URL.

The chain links icon can be used to enter an external link as well as any internal one.

Using images

If you wish to include an image in your page, you must first upload the image to the Wiki. You can then refer to it with your text.

To upload the image, use the Upload file option in the toolbox in the navigation bar on the left. Once uploaded you may insert your image on your page using double square brackets, the word 'file:' and the filename. Example [[File:map.jpg]]

Help:Contents/Editing