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 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 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 at the bottom. This ensures it belongs to the 'concept' category. So 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 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.