Difference between revisions of "Gentoo Wiki:Guidelines"

From Gentoo Wiki
Jump to:navigation Jump to:search
m (→‎Use lead-in sentences: Fix 404'd link. Thanks, ris.)
(→‎Block-level layout elements: Add Emerge template to block level elements as suggested by xxc3nsoredxx on talk page. Other minor readability changes.)
Line 198: Line 198:
 
|-
 
|-
 
| {{tl|RootCmd}}
 
| {{tl|RootCmd}}
| To display an administrative command with optional output. Please only use this for commands (or in situations) that require root privileges. The example here may appear near the end of the process of installing Gentoo. <br /><br /> '''Note:''' If the command output is verbose (more than 5 lines) use the <code>collapse-output=true</code> parameter to create an 'Expand' link.
+
| 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. <br /><br /> '''Note:''' If the command output is verbose (more than 5 lines) use the <code>collapse-output=true</code> parameter to create an 'Expand' link. This helps articles have a better flow for the reader.
 
| {{RootCmd|umount /mnt/gentoo}}
 
| {{RootCmd|umount /mnt/gentoo}}
 +
|-
 +
| {{tl|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.
 +
| {{Emerge|sys-apps/portage}}
 
|-
 
|-
 
| {{tl|Invocation}} and {{tl|RootInvocation}}
 
| {{tl|Invocation}} and {{tl|RootInvocation}}
Line 267: Line 271:
 
|}
 
|}
  
'''Note:''' While the various [[#In-line layout elements|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, or any of the *Box templates.
+
'''Note:''' While the various [[#In-line layout elements|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 ===
 
=== Use of newlines ===

Revision as of 18:05, 10 August 2022

Important
Please come back and check this page regularly. Feel free to discuss these guidelines and propose new ones on the associated Discussion page.

These guidelines are 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, 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 <code> to <var> 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 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[1]; 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 encourage 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[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.

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 hateful speech such as obscenities and 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.

Properties

Article description

Semantic MediaWiki, which is an extension used by the Gentoo wiki, extends MediaWiki functionality to add better support for annotating semantic data within wiki pages. The primary benefit used across the wiki is the Article description text property, which is set on a large number of pages.

Article descriptions should be set in the lead-in or introduction sections of articles. Doing so will enable a smart 'reuse' of data from the article inside other articles around the wiki (particularly by the {{See also}} template).

Input Rendered output Use case Example within text
Firefox is [[Article description::Mozilla's web browser.]] Firefox is Mozilla's web browser. Sets the Article description text property so that the annotated text can be referenced in other articles. Firefox — Mozilla's web browser.

To obtain a better understanding for what this looks like, see the Article description 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 a 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 <kbd>...</kbd>).
Now set the USE variable to -alsa to disable ALSA support.
{{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 is implemented by the {{c}} template.

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 press or key combination, use instead the {{Key}} template (discussed next).
  • When referring to input that is about to be illustrated using a block-level element such as "Cmd" or "RootCmd", then stick with the {{c}} template.

Remember that the <kbd> tag gives a high-contrast element which can hinder readability if overused.

List the fingerprint with gpg --fingerprint.
{{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 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.
{{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.
{{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"
{{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'
{{CodeBox}} To display code (with optional syntax highlighting) that does not fall into any other category listed above.

Note: HTML and wiki markup (including links) in this template is to be avoided.
CODE An example ebuild function
src_compile() {
  escons CC="$(tc-getCC)" FOO=1
}

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

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 said in the sentence above, simplifies the translation effort used by the community.

Linking

Use HTTPS when possible

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.

Do not oversaturate

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 avoid too much visual inefficiencies in a small spaces, contributors should avoid linking in small sections of text that that are critical to a document's visual structure. Generally speaking, it is not good prose to link in 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 dates and time representation

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}}

The {{Talk}} template will display the above code as:

Talk status
This discussion is done as of 2022-01-19.

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 should not be used in section headings.

Start of an article

A wiki article should start with a short introductory paragraph, without any heading. Somewhere the introductory paragraph should include a description of the article itself. Generally these description sentences are specially formatted with an Article description text property. See the associated formatting section above for details.

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 these prerequisite sections according to the concept.

Documenting a package or software title

When a package or software title is documented, add an InfoBox template 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:

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

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.

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 it may be a good idea to include a troubleshooting section in the body of the article.

As a general rule, it is not a good idea to create new sections that require another contributor to provide the content. Sections should be added on an as-needed basis. In other words, new sections should not be added until there is content with which to fill them.

Contributors who desire to draft new work can do so in their userspace and move new content to articles in the main namespace when finished.

References and links

At the end of the article, if resources are added, the following titles should be used:

  • "See also", which is used for links to articles, guides, how-tos, 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 use to delve into the topic more deeply.
  • "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 adding a reference, provide the following information[4] 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 -[5] and use those flags in their CFLAGS and CXXFLAGS 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. Referencing for beginners, Wikipedia. Retrieved on January 1st, 2015
  5. Michał Górny. Inlining -march=native for distcc, Michał Górny blog, June 23rd, 2014. Retrieved on January 1st, 2015.