Gentoo Wiki:Guidelines

From Gentoo Wiki
Jump to: navigation, search
Important
This page is still very much a work in progress. Please come back and check this page regularly. And feel free to discuss these guidelines and propose new ones on the Discussion page.

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, providing cleaner and more professional look. Guidelines also 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 <code> to <tt> 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[1]; they sound more professional and objective. 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[2]. This creates a nice flow of the text towards the action-oriented parts[3].

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.

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.

Input Rendered output Use case Example
''italics'' italics To emphasize something It is not possible to change the order of the configuration items.
'''bold''' bold To emphasize something strongly (when it is absolutely important for the user to notice it, such as when breakage might occur otherwise) Using the hyphen is absolutely necessary as otherwise the system will fail to boot.
<var>foo</var> foo Used for in-paragraph variable names (such as USE) Set the USE variable to alsa if audio support is desired.
<code>foo</code> foo Used in case of
  • A value of a variable (such as -alsa when referring to the USE flag)
  • Small chunks of code that are displayed in-line
  • Arguments or options to a command (in explanatory paragraphs - if it is used for the user to actually type in, use <kbd>...</kbd>)
Now set the USE variable to -alsa to disable ALSA support.
{{c|wheel}}[4] wheel Denotes a command or technical concept. Used with
  • Items that have a specific meaning ("wheel" refers to the wheels on a car, while wheel refers to the Linux group whose members are allowed to execute su)
  • Commands (such as less) that are either not to be invoked directly in the context of the paragraph, or which are shown in an example following the current paragraph
The root user is part of the wheel group (which can be updated through the gpasswd command).
<kbd>user input</kbd> user input Used for user input, which can be a command, or answer to a prompt, but with the following constraints:
  • When the input is a key or key combination, use the Key template instead
  • When the input is shown through an example, such as through the command boxes (like {{UserCmd}}, {{RootCmd}}, etc.), then stick with the {{c}} template

The second constraint is put in place as the <kbd>...</kbd> tag is a high-contrast tag which should not be overly used in a guide as to improve readability.

List the fingerprint with gpg --fingerprint.
{{Key|Alt}}+{{Key|F1}} Alt+F1 Key combination that the user needs to type in, most of the type as a reaction against a prompt or as special key combination in an application environment. Switch back to the first terminal using Alt+F1.
{{Keyword|~arch}} ~arch Use this template when referencing architecture keywords. For more information see the Keyword template. Packages that are still in testing can be installed by adding ~amd64 to the end of each package atom in the /etc/portage/package.accept_keywords file.
{{Path|/path/to/file}} /path/to/file Used for file and directories. In case of directories, one might want to add in the leading / as well. Next, edit /etc/hosts to add in the newly created hostname.

The use of the {{c}} 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 less, more, and so on).

Block-level layout elements

These elements are rendered on the block-level. They elements create line breaks (new lines) and are used to show more detail than is possible using the in-line elements mentioned above. The following table details the common block-level templates and their use case.

Input Rendered output Use case Example
{{KernelBox}} A paragraph breaking KernelBox. To display details on kernel features. See the KernelBox template for additional usage information.
KERNEL Example KernelBox
Kernel features displayed here.
{{CodeBox}} A paragraph breaking CodeBox. To display code. See the CodeBox template for additional usage information.
CODE Example CodeBox
Code displayed here.
{{FileBox}} A paragraph breaking FileBox. To display the contents of a file. See the FileBox template for additional usage information.
FILE FilenameExample FileBox
File contents displayed here.

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.

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.

Blocks and templates

Use Templates where appropriate.

A Note is usually following a block with some additional information, like so:

root #fuser /tmp
Note
The location can also be /var/tmp depending on the setup.

The use of the Important template is when special attention is needed - it gives a stronger signal to the user than a regular paragraph with some emphasizes would give.

The Warning template is when the user really needs to pay special attention as otherwise breakage might occur.

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 CONFIG_FOOBAR notation.

KERNEL Enabling evdev
Device Drivers --->
  Input device support --->
    <*>  Event interface

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

FILE /etc/portage/make.confSetup make.conf for LIRC
# (Replace "devinput" with the proper driver)
LIRC_DEVICES="devinput"
USE="lirc"

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

user $ls -l
total 112
-rw-r--r--. 1 root root   2048 Dec 30 19:32 courier.fc
-rw-r--r--. 1 root root     23 Dec 29 18:42 courier.if

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

root #umount /mnt/gentoo

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

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.

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 InfoBox to the beginning of the article, in which external resources such as the project homepage, wikipedia article, and/or ohloh statistics are summed up:

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

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 {{reflist}} 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 <ref> tag should be used. There is a subtle difference between an external resource and a reference:

  • an external resource is a location where the user can find more information about the subject which goes beyond a single claim used within the article
  • a reference is a location where the user can find more information (or proof) about a particular claim or statement made within the article

When using a reference, use the following information[5] 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:

CODE Example use of a reference
Users should replace <code>-march=native</code> with the various compiler flags that GCC finds for the native
system by using <kbd>gcc -march=native -x -c -</kbd><ref>Michał Górny.
[http://blogs.gentoo.org/mgorny/2014/06/23/inlining-marchnative-for-distcc/ Inlining -march=native for distcc],
[http://blogs.gentoo.org/mgorny/ Michał Górny blog], June 23rd, 2014. Retrieved on January 1st, 2015.</ref> and
use those flags in their <code>CFLAGS</code> and <code>CXXFLAGS</code> variables.

References

  1. Geoff Hart. Use of first, second, and third person in technical writing?, Technical Writing lists, August 17, 2005. Retrieved on January 1st, 2015
  2. Placement of the Topic Sentence, Rochester Institute of Technology, October 10, 2014. Retrieved on January 1st, 2015
  3. Alan S. Pringle, Sarah S. O'Keefe. "Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content", Page 112 on "Introducing the procedure", Scriptorium Publishing Services, Inc. ISBN 978-0970473363
  4. This replaces the <tt> tags previously used for this. The tag is deprecated in HTML5 and thus being phased out.
  5. Referencing for beginners, Wikipedia. Retrieved on January 1st, 2015