About category guidelines

Categories are used in three ways:

Belongs to

A page belongs to a category to indicate that it provides a substantial amount of useful information about a concept; usually the concept is the primary subject of the page. Typically by including the text [[Category:concept]] at the bottom of the page.

Links to

A page links to a category page to provide a useful reference for more information; typically "see the section [[:Category:concept|about concept]]". (Notice the : between "[[" and "Category")

Authority

The category page for a concept should be authoritative for Mer - if it points to or provides bad information, that's a major bug. More details below.

We then use the 'About' category to group concept pages together.

Guidelines

Creating a page that belongs to a category

Create a normal page and add [[Category:concept]] at the bottom. This ensures it belongs to the 'concept' category. So [[Category:spectacle]] would add a page to the list on the spectacle category page.

Note that nothing appears directly in the text but the bottom of the page will have a link like: "Categories: concept".

Think carefully before creating a new category.

Creating the category page

Follow a link to the Category page and edit it as if it were a normal page (see the others for ideas). Add [[Category:About]] at the bottom to ensure it is visible from the Category:About page as well as the Special:Categories page.

Think carefully before creating a new category.

Note that you only need to link to external pages - internal links are managed automatically.

Usage

These pages can be referred to 'inline' in other wiki pages to avoid repetition.

Eg the step by step adaptation guide doesn't need to explain how to install mic2 or run mic2 (or even what mic2 is)... it simply refers to the [[:Category:mic2]] page.

What to include

Each category MUST have it's own page and this should provide a minimal useful amount of information tightly scoped to a concept; essentially a summary.

Links to internal wiki pages will automatically be present.

External links should be provided to other information sources such as:

• installation guides
• reference documentation
• tutorials
• wikipedia pages
• upstream/home pages
• git repositories
• OBS project location (eg Mer:Tools etc)
• service instances
• etc etc

The categories

Titles

• should use lowercase even for acronyms: so :Category:osc and :Category:boss.
• They should be one or two words : ":Category:community obs"
• Don't use "the": as in ":Category:the community OBS".

Category usage

Don't hyperlink every occurence of a concept found in the categories. Usually just the first one per document will suffice; more is OK if it's a large document read in sections or for different concepts such as installation and usage.