User:SwifT/Styleguide

Welcome to the Gentoo Wiki. In this article, we provide the guidelines for handling articles on the wiki.

Rationale
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, giving a much cleaner and more professional look. Also, this allows for better cooperation across articles as all editors work using the same guidelines and styles.

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 at all.

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

Avoid first person
As 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, as reported fact.

Third person and passive voice are preferred, as they sound more professional and objective. The user can be addressed as "you" where appropriate, but it is discouraged to do so. For instance, do not use "You should now install the package" but use "Next, install the package". Similarly, "You can opt to only install the client" can be rephrased as "It is possible to only install the client".

Use lead-in sentences
Before any operation, create a lead-in sentence.

Instead of just having a section called "Installation" that immediately gives a, create a lead-in sentence like "Install the software using emerge:".

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

Titles and section headings
The title of an article should be short, specific and unambiguous. Full capitalization 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 small caps. 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 should not be used by contributors.

Introduction
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, wikipedia article, and/or ohloh statistics are summed up:

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.

Wiki structure
This section describes the structure of the wiki in general.

Categories
When a category has subcategories, pages should be assigned to the sub-category.

Add the article to one or more categories. Categories should be stated at the bottom.

Layout
Try to follow these layout principles as much as possible.

In-line layout elements
In-line layout elements are elements that are rendered within a paragraph. The next table shows the most common elements and their use case.

Use of newlines
There should be an empty line above a heading and below. This improves readability by editors (wiki syntax) and simplifies the translation effort used by the community.

Keep paragraphs short (generally one to five sentences) as that makes the article easier to read. It also simplifies the translation effort used by the community.

Blocks and templates
Use Templates where appropriate.

Use a KernelBox to display to the reader which Linux kernel configuration settings need to be applied. The content should be obvious for users on how to reach the particular configuration setting. Do not use the short-hand  notation.

Use a FileBox to display (a part of) the contents of a file.

Use a Cmd to display a non-administrative command (with output if applicable).

Use a RootCmd to display an administrative command (with output if applicable).

Use a CodeBox to display code snippets. Do not use CodeBox for file content or command output.