Gentoo Wiki:Guidelines

These guidelines are Article description::a set of suggestions for adding, editing, and removing content on the Gentoo wiki. More basic information about formatting text using wiki markup (section headings, lists, and so forth) and how to create a new page can be found elsewhere.

There are a number of reasons why a guideline (or style guide) is necessary for the wiki.

First of all, it creates a consistent look and feel of all articles on the wiki, providing cleaner and more professional presentation of knowledge. Guidelines allow for better cooperation across articles since all editors work using the same guidelines and styles as an authority.

Second, it reduces the likelihood that contributors continuously update the layout of an article, for instance switching variable names from  to   and back. Such changes too often trigger people (through the wiki watchlist) that want to watch over the content of the page, making it hard to keep track of changes in an organized manner. It also puts unnecessary stress on the infrastructure with little to no gains in article quality.

Third, it allows for contributors to easily get accustomed to writing on the wiki. It lowers the fear of making bad edits and aids in the discussion of acceptable edits.

This document is not meant to be fully exhaustive as this could lead to a reduction in contributions, where editors feel that it has become too rigid or difficult to understand the rules and guidelines on editing this wiki. Do not be afraid to make an edit, and making bad edits (unwillingly) is nothing to worry about — we have plenty of editors that will adjust your edit up to the standard of the Guidelines. Even the best editors make bad edits. Remember: the wiki is a collaborative effort!

Writing style
The writing style of wiki articles describes how the article itself should be written. It covers the language aspects of the articles.

Avoid first person
Since the wiki is a community effort and the content pages are informational, there should be no mention of "I" or "we". Articles should be written in third person: reported as fact.

Third person and passive voice are preferred ; we argue these sound more professional and objective; especially for technical instructions.

The user can be addressed as "you" where appropriate (which is called "second person writing"), but it is discouraged to do so. For instance, do not use "You should now install the package" instead use "Next, install the package". Similarly, "You can opt to only install the client software" can be rephrased as "It is possible to only install the client software".

Use lead-in sentences
Before any operation, create a lead-in sentence or topic sentence. This creates a nice flow of the text towards the action-oriented parts.

For instance, instead of immediately starting with an Emerge box to inform the user how to install a package, first create a simple sentence such as "Install the software on the system:".

Use American English
There are several flavors of English in the world. To keep a consistent layout, it is advised to stick with the American English (also known as US English). This will keep spelling homogeneous across the wiki.

Formatting
Try to follow these formatting principles as much as possible.

Inline layout elements
Inline layout elements are rendered within running text in a paragraph. They do not interrupt the flow of the text, unlike the block-level layout elements discussed in the next section. This table shows the most common elements and their use cases.

Note that the use of the  template for commands is to ensure that commands are not mistaken for parts of the English sentence itself. Linux (and Unix in general) often borrows English words for commands (think about, , and so on). It replaces the  tag which has been deprecated in HTML5.

Block-level layout elements
These elements, all implemented using templates, are rendered on the block level. That is, they create paragraph-ending line breaks and are displayed inside of a "box". They typically involve more content, rendered with more complicated formatting than is possible using the inline elements mentioned above. The following table details the common block-level templates available on this wiki and their use cases.

Follow the linked template names to see further information about using these templates. (See also Help:Templates and the complete list of all existing templates.)

Note that while the various inline formatting templates like c, Keyword, Path, and Package may freely be used inside of a Note, Important, or Warning template, they should never be used inside of a Cmd or RootCmd template, and should not be used in a KernelBox, FileBox or CodeBox template, except possibly in the title line.

Use of newlines
There should be an empty line above and below section headings and around any paragraph-breaking (not inline) templates. This improves readability by editors (wiki syntax) and simplifies the translation effort used by the community. Gentoo wiki editors should avoid the use of HTML's line break element, accept where absolutely necessary to archive the desired formatting results.

Keep paragraphs short; generally one to five sentences should be adequate. This makes the article easier to read and, as said in the sentence above, simplifies the translation effort used by the community.

Linking
Gentoo infrastructure, as well as the majority of large internet companies, have made the wise transition to HTTPS for most of the Gentoo sites. Whenever possible use HTTPS for external links instead of HTTP. The developers behind Gentoo would like to facilitate safety and security wherever possible, documentation is no exception.

Article contributors should only link once to other articles or resources (or, in large articles, once per main section). Review Wikipedia's Repeated links section in the Manual of Style for more information.

Avoid URL shortening
Please do not use URL shortened links on the wiki. They are avoided for two reasons:


 * 1) Users have no indication what the link destination is. It could be an inappropriate site or some other place they do not want to visit.
 * 2) The link could be used for tracking purposes. This should not be happening unless the user makes the decision to actually travel to a destination server (so there should be no third party intercepting the request).

Article structure
This section describes the structure of specific articles, depending on their type and purpose.

Article blueprints have been created to aid in new article creation. These provide a pre-defined structure for articles of various types; it is easier to remove structure than to add new structure. They also help keep Gentoo wiki articles uniform. Follow the rules below when adding content an article blueprint.

Titles and section headings
The title of an article should be short, specific and unambiguous. Full capitalization (title case) should be avoided as much as possible.

The title of a section (also known as "section headings") within an article should start with a capital letter, but the rest of the section title should use lower case (with the exception of proper nouns). This is called sentence case.

Section headings should be level 2 or higher (3, 4, ...). The use of a level 1 heading is meant only for the title of the article itself, and is automatically used. As such, level 1 headings have no reason to be defined in the article's text by wiki contributors.

Links and HTML formatting can be used if the end result provides more informations for the end-user to use and is linked to another Gentoo wiki page.

Start of an article
A wiki article should start with a short introductory paragraph, without any heading.

Headings such as Introduction or Overview are discouraged. If the article requires any conceptual knowledge before the operational content of the article can be given (such as installation instructions, configuration instructions, package administration tasks, etc.) name the section according to this concept.

Documenting a package or software title
When a package or software title is documented, add an  to the beginning of the article, in which external resources such as the project homepage, the category/package information (links to packages.gentoo.org), wikipedia article, and/or ohloh statistics are summed up:

When adding external links to an InfoBox use HTTPS whenever possible.

If there is need for conceptual information about the software title or package, then the first section of the article should be properly named (after the concept that is explained - do not use a generic title like Introduction or Concepts).

Next, follow with a section on the configuration of the software title or package on a Gentoo Linux system. This section includes information on USE flags, installation instructions and so on.

Next, follow with one or more sections on the operational aspects of the software title or package. Try to structure this section on a use-case basis, so that an entire operation is contained within a subsection. "Listing boot entries" or "Deleting encryption keys" are examples of good sub sections, whose main section could be called "Manipulating the boot entries" or "Encrypting volumes with cryptsetup".

Finish up with references to more in-depth material about the software title or package.

References and links
At the end of the article, if resources are added, the following titles should be used for these lists:


 * "See also" which is used for links to articles, guides, howto's and concept guides on the wiki.
 * "External resources" which is used for information and guides outside of the Gentoo wiki. These are resources that the reader will probably want to read up on to go more in detail on the topic.
 * "References" which is only to be used for the source references. This section should only include  to have the wiki automatically generate the list of references used in the article.

In case of the See also and External resources sections, try to inform the user why this resource is interesting to read or how it is related to the current article.

The References section is meant solely for the in-article references. Whenever the article takes information from an external resource as "fact" or source information to make further claims within the article, a in the given order (as far as that information is known):
 * 1) Author of the source
 * 2) Title of the source (as hyperlink)
 * 3) Main origin of the source, such as the main site (as hyperlink)
 * 4) Date of publication
 * 5) Date of retrieval of this information

For instance: