WikiCleanup

Freezes for FocalString Freeze: March 26, 2020 / Non-language packs: April 9, 2020

This page provides advice on cleaning up wiki pages, including information on common problems and how to correct them.

Objectives of wiki cleanup

  • Pages should be easy to read and should have a logical structure which makes it easy to find information
  • Spelling, punctuation and grammar should be correct
  • The formatting of a page should be consistent with other pages, so as to avoid confusion
  • Instructions should be correct and up-to-date - trying to follow incorrect instructions can be very frustrating

Most of the points above can be addressed by ensuring that a wiki page follows the Wiki Guide.

Common problems

Below is a categorised list of problems commonly-found on pages which need to be cleaned-up.

Formatting

Formatting issues are often minor, but correcting them can have a significant impact on how readable a page is.

Incorrect list formatting

Lists which have a large amount of text for each list item can be difficult to work with. For example, if you want to have several paragraphs per list item, you must be careful to indent those paragraphs correctly. Otherwise, when you insert the next list item, the numbering will start from 1 again.

Because of this, many authors number their lists manually (example). This should be avoided, as Moin will not recognise this text as being a list. Instead, use indenting to control the paragraphs:

 1. List item one (note one leading space)
  Paragraph 1 (note two leading spaces)

  Paragraph 2

 1. List item 2
  Paragraph 1

  Paragraph 2

See Help on Lists for more information on lists and indenting.

Inconsistent GUI item formatting

When an item in a GUI (such as a button or label) is referred to, it is common practice to emphasise that item. This helps users to find the names of the GUI items that they are looking for more easily in the text. However, the formatting of these items can vary greatly - while some authors use italics to denote labels, others may use bold text. It is important to be consistent so as to reduce confusion. Also, consistent formatting looks more professional.

Note: Many people use the "→" character (U+2192 RIGHTWARDS ARROW) to separate menu entries. This can be difficult to find (as it doesn't appear on a standard keyboard) and may not appear in all fonts. Use "->" instead, even though it doesn't look quite as good!

Use the following conventions when referring to GUI items:

Item

Description

Example

Button

Any button, such as push buttons and buttons on toolbars

Press Finish to complete the procedure.

Label

Text which labels other controls, such as text entries, lists, comboboxes, checkboxes and sliders

Type your name into the Name text box and then select your title from the Title list.

Menu entries

Instructions on how to navigate menus, such as the Applications menu on the desktop or the File menu in an application

Press Applications -> Accessories -> Text Editor to start a text editor.

File names

The names of files used in instructions

Open /etc/X11/xorg.conf in a text editor.

By default, Moin changes capitalised words which are joined together into a link to a wiki page, e.g. TextEditor. However, sometimes it is necessary to use joined-up words which aren't links, for example when you refer to OpenOffice. You can prevent Moin from inserting a link by breaking the word up with six apostrophes:

Open''''''Office

Structure

This section covers common structural errors.

Subsection title directly under section title

Authors often put a subsection heading directly beneath the heading of that subsection's parent (example, see "Hints and Tips" section).

It is recommended that a short description of the purpose of the main section is put directly under the main section heading. This helps readers to determine whether the section is relevant to them, and may serve to explain the section title more fully, for example:

= Hints and Tips =

This section provides a selection of hints and tips that you may find useful, such as keyboard shortcuts.

== Some Blender Shortcuts ==

Section heading directly under the page title

Some pages have a heading immediately underneath the page title (example), which normally says "Introduction", or repeats the page title.

In most cases, it is better to put a short description of the page between the page title and the first heading (example). This should give the reader an idea of what the page is about.

When a section heading is used to repeat the page title, it is often there to present the title in a human-readable format rather than as a wiki page name (example). Instead of using a section heading, you can override the wiki page name with something human-readable. To do this, insert a line such as the following at the top of the page (example):

#title The Title of This Page

Poor section names

The name of a section should be descriptive but succinct. Section titles are often listed in a table of contents at the top of the page, so should have names which make it obvious what each section covers. Names which are long and confusing (e.g. Case #1: fixed-address premium link + cheap broadband connection) or which don't provide any information (e.g. Secret sauce) should be avoided (example).

Miscellaneous

This section lists miscellaneous issues which you may come across.

Use of CategoryDocumentation category

Many pages on the help wiki are members of the CategoryDocumentation category. All of the pages on the help wiki should be documentation, so it is not necessary to use this category. Remove this category if you see it used on a page.

Long, difficult to read page titles

By default, Moin uses part of a page's URL as its wiki title. If the page is called TextEditors, this is not too much of a problem, as the title is still easy to read. However, more complex titles often become difficult to decipher (example).

You can override the wiki page title to make it easier to read by inserting a line similar to the following at the top of the page:

#title This is a page title

Try to keep the page title broadly similar to the actual page name, while omitting unnecessary information from the URL. For example, InternetAndNetworking/DualHomedGatewayDHCP would become Dual-homed DHCP Gateway.


CategoryDocteam