The Mer Wiki now uses your Mer user account and password (create account on https://bugs.merproject.org/)


About category guidelines

From Mer Wiki
(Difference between revisions)
Jump to: navigation, search
(use About - makes more sense - and hide the editing guidelines from casual browsing)
 
(Clarify - thanks for the heads up smoku)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
An 'About' category is used to group these concept pages together.
+
Categories are used in three ways:
 
+
The 'About' categories are used in two ways:
+
 
; Belongs to
 
; Belongs to
: A page belongs to an About 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.  
+
: 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 <nowiki>[[Category:concept]]</nowiki> at the bottom of the page.
 
; Links to
 
; Links to
: A page links to category to provide a useful reference for more information; typically <nowiki>"see the section [[:Category:concept|about concept]]"</nowiki>. (Notice the : between "[[" and "Category")
+
: A page links to a category page to provide a useful reference for more information; typically <nowiki>"see the section [[:Category:concept|about concept]]"</nowiki>. (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  [[:Category:About|'About' category]] to group concept pages together.
 +
 
  
 
= Guidelines =
 
= Guidelines =
== Creation ==
+
 
Create a normal Category page and add <nowiki>[[Category:About]]</nowiki> at the bottom to ensure it is visible from the [[:Category:About]] page as well as the [[:Special:Categories]] page.
+
== Creating a page that belongs to a category ==
== Usage ==
+
Create a normal page and add <nowiki>[[Category:concept]]</nowiki> at the bottom. This ensures it belongs to the 'concept' category. So <nowiki>[[Category:spectacle]]</nowiki> would add a page to the list on the [[:Category:spectacle|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 <nowiki>[[Category:About]]</nowiki> 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.
 
These pages can be referred to 'inline' in other wiki pages to avoid repetition.
  
 
Eg the [[Adaptation Guide/Step by step|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 <nowiki>[[:Category:mic2]]</nowiki> page.
 
Eg the [[Adaptation Guide/Step by step|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 <nowiki>[[:Category:mic2]]</nowiki> page.
  
== What to include ==
+
=== 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.
 
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.
  
Line 31: Line 47:
 
* etc etc
 
* etc etc
  
== The categories ==
+
=== The categories ===
  
 
Titles
 
Titles

Latest revision as of 15:30, 21 January 2012

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.


Contents

[edit] Guidelines

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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

[edit] 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".

[edit] 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.

Personal tools