User:SwifT/DocumentingPackagesOnTheWiki

From Gentoo Wiki
Jump to: navigation, search

In this document, I try to put my thoughts down on how I believe packages are best documented on the wiki.

Structure

A wiki article best starts with the introduction; it is one (or at most two) paragraphs explaining what the package is and its purpose. An infobox should be used to refer to the package official documentation, which explains the package itself in more detail.

CODE Example infobox
{{InfoBox stack
|{{InfoBox wikipedia|TitleOnTheWikipedia|header=true}}
|{{InfoBox homepage|http://url/to/homepage}}
|{{InfoBox ohloh}}
}}

Add the header=true on the top one.

  • Wikipedia one does not need a title part if the title is the same

Concepts (optional)

An optional, first section should explain the concepts related to the package. This is optional if the concepts are well known, but in some cases it might be important to explain the concepts.

In the conceptual section, references can be used towards other resources to guide the user into understanding something in more detail.

Configuration

This section explains how to configure the package within the Gentoo context. It includes the installation as well of course, although this usually just refers to the emerge command.

Operations related to a concept

Next, sections (multiple) are used to provide the operations related to the concept. Focus on "quick start" approaches; not a fully detailed one - those either need a separate document, or should be part of the upstream project.

See also

Add in a list of related resources to look into (hosted on the wiki).

External resources

Add in a list of related resources to look into (hosted outside the wiki).