5,838
edits
Help:Contents/Editing: Difference between revisions
Styling rules section added, Renaming and redirect sub-section added
m (Restructure the page, so important information is at top not bottom!) |
(Styling rules section added, Renaming and redirect sub-section added) |
||
| Line 1: | Line 1: | ||
=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 | |||
*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= | =Creating a new page= | ||
{{TOCright}} | |||
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. | 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. | ||
| Line 17: | Line 40: | ||
'''Be careful''' a reference to (for example) <nowiki>[[webTags]]</nowiki> would create a new page, as that capital '''T''' in the middle is different to the name of the existing '''Webtags''' page. | '''Be careful''' a reference to (for example) <nowiki>[[webTags]]</nowiki> would create a new page, as that capital '''T''' in the middle is different to the name of the existing '''Webtags''' page. | ||
==Renaming and Redirect== | |||
If you are [[Special:RequestAccount|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'' <nowiki>[[old-page-name</nowiki> and '''replace with''' <nowiki>[[new-page-name</nowiki>. | |||
| Line 22: | Line 55: | ||
'''Remember: In the Cumulus Wiki you can only edit/create pages if you are [[Special:RequestAccount|Registered]] and Logged in.''' | '''Remember: In the Cumulus Wiki you can only edit/create pages if you are [[Special:RequestAccount|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. | 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== | ==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. | 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. | We log who changed the page, and when, so your username will appear on the 'History' tab. | ||
| Line 82: | Line 127: | ||
====Underline==== | ====Underline==== | ||
use the HTML markup for underline. <nowiki><u></nowiki> tag at the start and <nowiki></u></nowiki> at the end of your word of phrase. | use the HTML markup for underline. <nowiki><u></nowiki> tag at the start and <nowiki></u></nowiki> at the end of your word of phrase. | ||
| Line 93: | Line 139: | ||
===Creating Sections=== | ===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 at the top (as with this page). | 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 at the top (as with this page). | ||
All you need do is mark your headings appropriately. WikiText will then automatically create the sections, deal with all the formatting of headings, and make the page look good. | *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. | |||
If you create more than three sections, the Wiki will automatically generate a contents page at the top of the page. | **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 at the top of the page. | |||
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 <nowiki>{{TOCright}}</nowiki>. | 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 <nowiki>{{TOCright}}</nowiki> as this page does. | ||
Sections can be arranged in a hierarchical manner: | Sections can be arranged in a hierarchical manner: | ||
| Line 107: | Line 156: | ||
****The fourth level will have four equals signs each side of the heading | ****The fourth level will have four equals signs each side of the heading | ||
It is possible to go to lower levels. Sections will be numbered, with subsection numbers separated from section above number by a full stop. | 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. | |||
<br/> | |||
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. | 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. | ||