Gentoo Wiki:Guidelines

Wiki Help pages
Contributor's guide — Guidelines — Fixing errors howto
Editing pages — Talk pages — Formatting
Code of conduct — Wiki project page — About Gentoo wiki — Wiki FAQ
Help improve the documentation! — Contributing to Gentoo

See also
These guidelines provide advice on how to best write and lay out articles. To learn how to begin editing the Gentoo wiki, the best place to start is the contributor's guide.

The Gentoo wiki guidelines provide writing-conventions and layout-schemes that aim for a consistent and professional presentation across all of the wiki's diverse articles. They work as a style-guide and reference on how to best write and collaborate on articles.

By following the guidelines, editors can help provide the community with good-quality, readable, useful information, that presents things clearly, and remains consistent across all of the documentation.

Although any edit to the wiki that adds useful information or corrections is a valuable contribution, edits that conform to the guidelines will greatly help other editors concentrate their efforts on improving content. That said, never be afraid to make an edit! Making bad edits (unwillingly) is nothing to worry about — other editors will eventually fix up contributions to conform to the guidelines: the wiki is a collaborative effort!

Feel free to discuss the guidelines, or even to propose new ones, on the associated discussion page.

Important
Anyone making more than infrequent trivial edits to the wiki, please read and follow the guidelines. Changes to this document will accrue over time, so please come back and check this page regularly.

See also
Further information about editing the wiki can be found in the help pages, for example in the formatting text using wiki markup or how to create a new page help articles.

Why guidelines?

The guidelines come with multiple benefits for the wiki, among which are:

1. The guidelines help maintain a consistent look and feel across articles, providing a cleaner and more professional presentation. Consistency helps the reader to not get distracted by needless changes in style and layout, and allows them to get comfortable with the wiki.
2. The guidelines allow for better cooperation, since all editors work using the same reference. They help avoid repeated purely cosmetic edits: without a clear reference, things like switching variable names from <code> to <var> and back can happen (such needless changes would send users unnecessary notifications and pollute change history, which would be distracting and make following article changes difficult).
3. The guidelines can help contributors get accustomed to writing for the wiki. By providing an adaptable structure around which to articulate articles, they can guide changes and provide reassurance when deciding how to organize content.
4. They provide a good reference from which to discuss how to best make progress both on articles and on policy.

Note that the guidelines are not meant to be fully exhaustive, as being overly-prescriptive could overwhelm new editors.

Writing style

The writing style of wiki articles covers the language aspects of the content. It aims to be clearly understandable, professional, and give a consistent style across articles.

Avoid first and second person writing

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

Third person and passive voice are preferred; we argue these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content.

The user can be addressed as "you" where appropriate (which is called "second person writing"), but contributors are discouraged from writing in this manner. 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".

Another commonly found example across the wiki is the possessive second person pronoun "your". It is seen in the context of "install the package on your system" or "run emerge --depclean to clean up your unused dependencies". Contributors are encouraged to rewrite these sections as "install the package on the system" or "run emerge --depclean to clean up the unused dependencies".

Editors are encouraged to clean up articles that use first and second person writing by rephrasing sections of text as is appropriate to the article.

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 when explaining how to install a package, precede the step with a simple lead-in sentence such as "Install the software on the system:".

Use serial commas

Serial commas should be used when defining lists. A serial comma is a comma placed after each item in a list of three or more items, including the penultimate term. Consider the following sentences as examples:

Without serial comma

CPU, RAM and motherboard are all common components in a desktop workstation.

With serial comma

CPU, RAM, and motherboard are all common components in a desktop workstation.

The second example is the preferred one: a comma follows each item in the list, including the item preceding the coordinating conjunction ("and" in the aforementioned examples).

Use American English

There are several flavors of English in the world. To keep a consistent layout of the content throughout the wiki, it is advised to stick with the American English (also known as US English). This will keep spelling and terminology homogeneous, and help avoid flip-flopping edits between different versions of spelling.

An exception to this guideline exists when directly quoting documentation that includes spelling or terminology inconsistent with American English. For example, when citing a man page of software written in British English, the corresponding British English style should be maintained without words being translated into their American English counterparts. This exception does not mean the entire section or article should be re-written in British English, as it applies exclusively to the citation.

Use clean language

Language used on the wiki is to be kept to a "G" rating. The "G" in this case does not stand for Gentoo; it stands for general audiences. Wiki content should be acceptable for all ages to consume. In practice, editors should avoid unhelpful speech such as obscenities, crassness, profanities in their edits to articles and summary messages. Please see the Gentoo Code of Conduct for more details.

Formatting

Contributors should try to follow these formatting principles when possible, since they directly impact the overall readability of articles across the wiki.

Those who are new to MediaWiki in general may find the generic formatting page helpful. It covers some elements not found in the sections below such as bullet, numbered, and definition lists, indentation, Unicode, and other topics.

Article description property

The [[Article description::]] property should be set on articles to provide a descriptive handle that can be automatically reused on other pages. Article descriptions are conventionally set in the lead-in sections of articles.

Article descriptions "capture" a section of text from an article to be used as the description property of that page, but in no way alter the rendering of pages. Select or write a section of text that properly describes the content or intention of an article, and surround it with the [[Article description:: and ]] tags.

The Article description property can be used in multiple ways across the wiki, for example the {{See also}} template leverages article descriptions to provide automatically-formatted, user-friendly, links in See also sections at the bottom of articles.

Here is a usage example:

Source input	Rendered output in article	Use with {{See also|Firefox}} template
Firefox is [[Article description::Mozilla's web browser.]]	Firefox is Mozilla's web browser.	Firefox — Mozilla's web browser.

The full list of pages with the Article description property on the wiki can be found here. Take a look at the source of any of those pages for concrete examples of how to use this property.

Semantic MediaWiki is used by the Gentoo wiki to add support for annotating semantic data within wiki pages, and this extension provides the article description text property.

Inline layout elements

Inline layout elements are rendered within the running text of a paragraph. They do not interrupt the flow of the text, unlike the block-level layout elements discussed in the next section. The wiki uses several different kinds of markup for inline text formatting, including wiki formatting, HTML tags, and wiki templates.

The following table shows the most common inline elements and their proper use cases:

Input	Rendered output	Use case	Example within text
''italics''	italics	To emphasize something.	It is not possible to change the order of the configuration items.
'''bold'''	bold	To strongly emphasize something, when it is very important for the reader to notice it. (See also the "Warning" block-level element below.)	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, FEATURES, or CFLAGS).	Set the USE variable to alsa if audio support is desired.
<code>foo</code>	foo	Used for: In-paragraph variable values (such as -alsa, referring to a value to set in the USE variable). 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 {{C|...}}</kbd>).	Now set the USE variable to -alsa to disable ALSA support.
{{Anchor|See also}}		Inserts one or more (up to 10) HTML anchors into a page at the specified location. This location can then be linked to using the syntax: [[#anchorname|link text]] - When linking from elsewhere on the same page. {{Link|#anchorname|link text}} - When using the {{Link}} template to link to elsewhere on the same page. [[Pagetitle#anchorname|link text]] - When linking to an anchor on a different page. {{Link|Pagetitle|section=#anchorname|link text}} - When using the {{Link}} template to link to an anchor on a different page. The {{Anchor}} template is required in section headers of base pages for pages that have been marked for translation (see the explanation below).	This is a special paragraph describing how to use the Anchor template..
{{c|wheel}}	wheel	Denotes a command or technical concept. Used with: Items that have a specific meaning (a wheel is something on a car, while wheel is 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. Note that this formatting behavior is implemented via the {{c}} template.	The root user is part of the wheel group (which can be updated through the gpasswd command).
{{Key|Alt}}+{{Key|F1}}	Alt+F1	Key combination that the user needs to type in, most of the time in reaction to a prompt or as a special key combination in an application environment. This is implemented by the {{Key}} template.	Switch back to the first terminal using Alt+F1.
{{Keyword|~arch}}	~arch	Use this template when referencing architecture keywords. See {{Keyword}} for more information.	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 files and directories. Be sure to include the leading "/" if it is an absolute path. In the case of directories, a trailing "/" (forward slash) may be helpful for easy readability. (See {{Path}} for other ways to use this template.)	Next, edit /etc/hosts to add the newly created hostname.
{{Package|category/package}}	category/package	Provides an inline link to package information at https://packages.gentoo.org (see the {{Package}} template for more information). Note that this is not the same as {{InfoBox package}}, which adds the link in an InfoBox.	Puppet is provided by the app-admin/puppet package.

Note that 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). It replaces the <tt> 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).

Template	Use case	Example
{{Note}}	To show additional information that should be set off from (or maybe cannot be included in) the text or block element that precedes it. The example shown here might follow a {{RootCmd}} (explained below).	Note Use grub2-install instead of grub-install if grub was installed with the multislot USE flag.
{{Tip}}	To provide a detail that is helpful to know, but not necessary to accomplish the preceding instructions.	Tip It is wise to make regular backups using the 3-2-1 backup technique. 3) Data should exist in three places, one place being originating data and two backup copies of the data. 2) Each of the two backup copies should be on different device types. For example one copy could be on a hard drive and the other copy on a Bluray disk. 1) One copy of copies of backup data should be off site, outside of the area which a local disaster could occur.
{{Important}}	To emphasize an item deserving special attention: it gives a stronger signal to the reader than normal inline emphasis would give.	Important Pay close attention to the following sections, as they provide crucial information to proper configuration of Portage.
{{Warning}}	To strongly emphasize something that the reader really needs to pay special attention to, as otherwise system breakage might occur.	Warning Consider the security implications of running chmod --recursive 777 ${HOME} as it will mark every file in the user's home directory as writable by every user on the system.
{{Cmd}}	To display a non-administrative command with optional output. Please only use this for commands that an ordinary (non-root) user can execute. Note: If the command output is verbose (more than 5 lines) use the collapse-output=true parameter to create an 'Expand' link.	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
{{RootCmd}}	To display a command running with superuser privilege (can optionally includes command output). Please only use this for commands (or in situations) that require elevated privileges. Note: If the command output is verbose (more than 5 lines) use the collapse-output=true parameter to create an 'Expand' link. This helps articles have a better flow for the reader.	root #umount /mnt/gentoo
{{Emerge}}	Provides a quick alias for installing software with superuser privileges. This template is typically utilized in the Installation sections of articles. At minimum, a package atom is expected for the unnamed parameter.	root #emerge --ask sys-apps/portage
{{Invocation}} and {{RootInvocation}}	Displays a user or administrative command's invocation options. These templates should only be used for command invocation; they presume output will be verbose and will create an 'Expand' link.	user $cat --help Usage: cat [OPTION]... [FILE]... Concatenate FILE(s) to standard output. With no FILE, or when FILE is -, read standard input. -A, --show-all equivalent to -vET -b, --number-nonblank number nonempty output lines, overrides -n -e equivalent to -vE -E, --show-ends display $ at end of each line -n, --number number all output lines -s, --squeeze-blank suppress repeated empty output lines -t equivalent to -vT -T, --show-tabs display TAB characters as ^I -u (ignored) -v, --show-nonprinting use ^ and M- notation, except for LFD and TAB --help display this help and exit --version output version information and exit Examples: cat f - g Output f's contents, then standard input, then g's contents. cat Copy standard input to standard output. GNU coreutils online help: <http://www.gnu.org/software/coreutils/> Full documentation at: <http://www.gnu.org/software/coreutils/cat> or available locally via: info '(coreutils) cat invocation' root #cat --help Usage: cat [OPTION]... [FILE]... Concatenate FILE(s) to standard output. With no FILE, or when FILE is -, read standard input. -A, --show-all equivalent to -vET -b, --number-nonblank number nonempty output lines, overrides -n -e equivalent to -vE -E, --show-ends display $ at end of each line -n, --number number all output lines -s, --squeeze-blank suppress repeated empty output lines -t equivalent to -vT -T, --show-tabs display TAB characters as ^I -u (ignored) -v, --show-nonprinting use ^ and M- notation, except for LFD and TAB --help display this help and exit --version output version information and exit Examples: cat f - g Output f's contents, then standard input, then g's contents. cat Copy standard input to standard output. GNU coreutils online help: <http://www.gnu.org/software/coreutils/> Full documentation at: <http://www.gnu.org/software/coreutils/cat> or available locally via: info '(coreutils) cat invocation'
{{KernelBox}}	To display details on kernel configuration. The content should make it obvious to users how to reach the particular configuration settings in, say, menuconfig. Do not use the short-hand CONFIG_FOOBAR notation. Note: HTML and wiki markup (including links) in this template is to be avoided.	KERNEL Enabling evdev Device Drivers ---> Input device support ---> <*> Event interface
{{FileBox}}	To display the contents (usually only partial contents) of a file. Syntax highlighting is supported for common programming languages. This example uses lang=bash. Note: HTML and wiki markup (including links) in this template is to be avoided.	FILE /etc/portage/make.confSetup make.conf for LIRC # (Replace "devinput" with the proper driver) LIRC_DEVICES="devinput" USE="lirc"
{{CodeBox}}	To display code (with optional syntax highlighting) that does not fall into any other category listed above. Note: HTML and wiki markup (including wiki style links) in this template is to be avoided due to how {{PreBox}} passes arguments to the underlying <syntaxhighlight> element. To highlight these markups use <syntaxhighlight> directly.	CODE An example ebuild function src_compile() { escons CC="$(tc-getCC)" FOO=1 }
<syntaxhighlight>	To display HTML and wiki markup (with optional syntax highlighting).	== Installation ==

Note
While the various inline formatting templates like C, Keyword, Path, and Package may freely be used inside of the Note, Important, or Warning templates. They should never be used inside of Cmd, RootCmd, Emerge, Invocation, or any other *Box templates.

Use of newlines

In the page source text, 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 <br /> line break element, except where absolutely necessary to achieve the desired formatting results.

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

Linking

Use HTTPS when possible

Gentoo infrastructure, as well as the majority of the web, long ago transitioned to HTTPS. 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!

Avoid oversaturation

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 linking in critical sections

In order to limit visual distraction, contributors should avoid linking in the small sections of text that that are critical to a document's visual structure such as section headers, page titles, templates, or template parameters (such as the title parameter of the {{FileBox}}, {{CodeBox}}, and {{KernelBox}} templates). Contributors who see links in these areas should remove them as necessary.

This linking guideline does not apply to template parameters that are intentionally supposed to be links such as {{InfoBox}}, etc.

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).

Avoid temporary file hosting sites

Linking to temporary file hosting sites such as pastebin, bpaste, or any other platform that removes links after a certain period of time should be avoided. Services such as GitLab's Snippets or GitHub's Gists are more favorable and can be conservatively used to link to larger amounts of text data (greater than 80 lines). This can be useful when sharing certain configuration files or scripts.

An exception to this guideline is granted for user namespace areas (User:) on the wiki.

Use ISO 8601 for date and time representatio

Wherever possible, use ISO 8601 for date and time representation across the wiki. The ISO 8601 date format is structured as "YYYY-MM-DD", where "YYYY" is the year, "MM" is the month, and "DD" is the day.

A typical area the YYYY-MM-DD format should be used is the date parameter in the {{Talk}} template. For example, use the following format when closing an open discussion:

{{Talk|closed|date=2022-01-19}}

This will display a cartouche including the properly formatted date to indicate that the discussion is closed (and will remove the discussion from the global list of open discussions on the wiki).

Article structure

This section describes how articles should be structured both in general, and for specific types of article which have their own particular structures (for example those describing a piece of software; or "meta articles" which describe a whole category of software).

Important
Article blueprints aid with article creation by providing a predefined structure for pages of various types - articles should follow these structures to provide consistency across the wiki.

Titles and section headings

The title of an article should be short, specific and unambiguous.

Titles both of articles and of sections within an article ("section headings") should start with a capital letter, with the rest of the title using lower case (with the exception of proper nouns). This is called sentence case. Full capitalization (also known as "title case") should be avoided.

Section headings should be level 2 or higher (3, 4, ...). A level 2 heading uses two equals signs, i.e.: "== <title> ==".

Note
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 (i.e. "= <title> =") should not be defined in the article's text by wiki contributors.

Links and HTML formatting should not be used in section headings.

Start of an article

A wiki article should start with a short introductory paragraph, without any heading. The introductory paragraph should include a description of the article itself, and often these description sentences will be used as the Article description property.

Headings such as Introduction or Overview are highly discouraged: this information should usually just be included in the article header (the text at the top of an article, before the first section heading).

If an article requires any conceptual knowledge before the operational content of the article can be given (such as installation instructions, required configuration, package administration tasks, etc.) name these prerequisite sections according to the concept.

Documenting a package or software title

Note
This section gives an overview of how to layout a specific type of article: articles for packages or software titles. For guidance on how to layout other common types of article, see the article blueprints.

When documenting a package or software title, add an {{InfoBox}} template to the beginning of the article, with external resources such as the project homepage, the category/package information (links to packages.gentoo.org), wikipedia article, ohloh statistics, etc.

Examples of what can be usefully added as InfoBox entries can be found in the software blueprint. Example of an InfoBox layout:

CODE <software title>

{{InfoBox stack
|{{InfoBox homepage|https://url/to/homepage|header=true}}
|{{InfoBox package|category/package}}
|{{InfoBox wikipedia|TitleOnTheWikipedia}}
|{{InfoBox ohloh}}
}}

Important
Remember to use HTTPS whenever possible when adding external links to an InfoBox.

Following the blueprint: software articles should start with the "Installation" section with installation instructions, USE flag information and so on. A "Configuration" section will usually follow that can have info about configuration files, environment variables, and configuring the launch of daemons for different init systems, for example.

The central part of these articles will usually be one or more sections on the operational aspects of the software title or package. Try to structure this part on a use-case basis, with each subsection containing an entire operation. Examples of good sections could be "Manipulating the boot entries" or "Encrypting volumes with cryptsetup". It is good prictice to split sections up, so that their subsections each cover just one operation; "Manipulating the boot entries" could for example be split into "Listing boot entries" and "Adding a boot entry", etc.

Body

Adding new sections

The article body should include sections that are pertinent to the reader. For example, if an issue is frequently encountered when setting up a specific software package, then include a troubleshooting section about that issue.

Sections should be created on an as-needed basis, so new sections should not be added until there is content with which to fill them. Do not create empty sections expecting another contributor to provide the content (note that the {{Todo}} template may be used to show that required content has been identified for an article).

Tip
New sections (or even whole articles) can be drafted in userspace and moved to articles in the main namespace when finished.

End of an article

An article should finish up with links to related material: other Gentoo wiki articles, external websites, or references to source material (through <ref> tags in the article body). These sections are optional, but should be included if any useful resources are available.

Tip
Remember to add the "References" section when any <ref> tags are used in the article.

At the end of the article, add the following sections, as appropriate:

See also section

Add See also sections to reference other articles on the wiki that are related to the current article, contain further information about the current subject, or can be of interest to people reading the current page.

See also sections should consist of bullet lists of {{See also}} templates. Check that articles referenced using this template have the correct "Article description", so that the proper descriptive information will be shown in the list.

It can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.

External resources section

An external resource provides more information about the subject at hand than is available on the wiki. These sections are similar to See also lists, but link to pages outside the Gentoo wiki. These are often resources to help delve deeper into a topic, reference material, complete documentation, etc.

"External resources" sections should consist of bullet lists of URLs to external websites. It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.

References section

Whenever an article takes information from an external resource as "fact" or as source information, a <ref> tag should be used to cite that resource. The References section is meant solely for these in-article references, and constitutes a sort of simple bibliography. Once the appropriate <ref> tags are in place, these sections automatically generated - just add the header and the {{reflist}} template:

== References ==
 
{{reflist}}

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 adding a reference, provide the following information in the given order (as far as that information is known):

1. Author of the source;
2. Title of the source (as a hyperlink);
3. Main origin of the source, such as the main site (as a hyperlink);
4. Date of publication; and
5. Date of retrieval of this information.

For example:

"Users should replace -march=native with the various compiler flags that GCC finds for the native system by using gcc -march=native -x -c - and use those flags in their CFLAGS and CXXFLAGS variables."

See also

• Contributing to Gentoo — explains how users can contribute to the development of Gentoo
• Gentoo Wiki:Contributor's guide — help anyone quickly get started with simple edits
• Gentoo_Wiki:FAQ — a collection of common questions about the Gentoo wiki, the documentation contained within, and editing the wiki, along with their corresponding answers
• Help:Contents — provide useful information about using the Gentoo wiki
• Help improve Gentoo by getting involved with documentation! — the areas where anyone can help improve the documentation for the benefit of both Gentoo users and unix(like) users across the Internet
• Project:Council/Code_of_conduct — describes Gentoo's Code of Conduct for public communication fora, as well as the action taken should it be broken.
• Project:Wiki — coordinates contributors to help make it easy to write the best possible documentation both for Gentoo users, and for the Unix(like) community at large
• What to do when noticing an error on the wiki — what to do when noticing an error on the wiki, to get things fixed