hello friends! new(ish)!

Help:Style

From InstallGentoo Wiki v2
Jump to navigation Jump to search

Please note that the guide is an official guide, and as such, this page is subject to constant improvements. The community can make suggestions by utilizing the talk page. Because of the mechanism of MediaWiki (Special:RecentChanges), we won't have to announce any addition/deletion to the guide.

These style conventions encourage tidy, organized, and visually consistent articles. Follow them as closely as possible when editing the wiki.

Article pages

Title

Note: This also applies to section titles and not just page titles.
  • Titles should use sentence case, e.g. "Title for new page" is correct, while "Title for New Page" is not. Note that common words that are part of a proper name or an upper-case acronym must be capitalized, e.g. "Advanced Linux Sound Architecture", not "Advanced Linux sound architecture".
    Namespaces are not considered part of titles, so "InstallGentoo Wiki:Example article" is correct, while "InstallGentoo Wiki:example article" is not. Subpage names should start with a capital letter, so "My page/My subpage" is correct, while "My page/my subpage" is not.
  • By default, the topic name in titles should be in the singular form; it should be in the plural form if it represents a group or class of something and is a countable noun or perceived as such.
  • If the subject of the article is commonly known both with the full name and the acronym, prefer using the full name in the title of the article. Do not include both the full name and the acronym (e.g. in parentheses) in the title, but rather use a redirect on the acronym page that points to the page titled with the full name.
  • See the Help:Article naming article for more information.

Layout

  • Order elements in an article as follows:
  1. #Magic words (optional)
  2. #Article status templates (optional)
  3. #Preface or introduction
  4. Table of contents (automatic)
  5. Article-specific sections
  6. External links (optional)
  7. See also (optional)
  8. #Categories

Magic words

  • Behavior switches — and in general, all of the magic words that change how an article is displayed or behaves but do not add content by themselves — should all go at the very top of articles.
    This rule applies in particular to {{DISPLAYTITLE:title}} and Template:Lowercase title, which makes use of the former.

Categories

  • Every article must be categorized under at least one existing category.
  • An article can belong to more than one category, provided one is not ancestor of the others.
  • Categories must be included at the bottom of every article, after #See also.
  • There should be no blank lines between categories and the first line of text (or interlanguage links, if present), because this introduces extra space at the top of the article.

Article status templates

  • Article status templates can be included right below the categories (or interlanguage links, if present) and right above the introduction (or the Related articles box, if present).
  • Article status templates can also be used inside article sections, when appropriate.
  • Always accompany an article status template with some words of explanation in the dedicated field (examples are provided in each template's page), possibly even opening a discussion in the talk page.

Preface or introduction

  • Describes the topic of the article.
    Rather than paraphrasing or writing your own (possibly biased) description of a piece of software, you can use the upstream author's description, which can usually be found on the project's home page or about page, if it exists.
  • Included right above the first section of the article.
  • Do not explicitly make an ==Introduction== or ==Preface== section: let it appear above the first section heading. A table of contents is shown automatically between the preface and first section when there are sufficient sections in the article.

Section headings

  • Headings should start from level 2 (==), because level 1 is reserved for article titles.
  • Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
  • Headings use sentence case; not title case: My new heading; not My New Heading.
  • Avoid using links in headings because they break style consistency and do not stand out well enough. Usually the anchor text is also found in the section content, otherwise you can use a simple sentence like:
See Some related article for more information.
For the same reason, also avoid using any kind of HTML or wiki markup code, including #Code formatting templates. See also Help:Style/Formatting and punctuation.

Code formatting

  • Use {{ic|code}} for short lines of code, file names, command names, variable names and the like to be represented inline, for example:
    Run sh ./hello_world.sh in the console.
  • For single lines of code (command line input or output code and file content) to be represented in a proper frame, simply start them with a single space character, see also Help:Editing#Code. For example:
$ sh ./hello_world.sh

Hello World
  • Use {{bc|code}} for multiple lines of code (command line input or output code and file content) to be represented in a proper frame, for example:
#!/bin/sh

# Demo
echo "Hello World"
  • Use {{hc|input|output}} when in the need of representing both command line input and output, for example:
$ sh ./hello_world.sh
Hello World
  • When you need to represent file content and you feel it may be difficult for readers to understand which file that code refers to, you can also use {{hc|filename|content}} to show the file name in the heading, for example:
~/hello_world.sh
#!/bin/sh

# Demo
echo "Hello World"
  • For blocks of code such as a configuration file, consider focusing the reader to the relevant lines and ellipsing (...) any surrounding, non-relevant content.
  • See the Help:Template article for more information and for troubleshooting problems with template-breaking characters like = or |.

Command line text

  • When using inline code (Template:ic), no prompt symbol is to be represented, but any notes about permissions must be added explicitly to the surrounding text.
  • When using block code (Template:bc or lines starting with a space character), use $ as a prompt for regular user commands; use # as a prompt for root commands.
    Note: Because # is also used to denote comments in text files, you should always make sure to avoid ambiguities, usually by explicitly writing to run the command or edit a text file.
    • The sentence introducing a command block should usually end with :.
    • Unless really necessary, prefer using: 
      # command
      instead of writing: 
      $ sudo command
    • Do not use the root prompt and the sudo command together, like in: 
      # sudo command
      The only exception is when sudo is used with the -u flag: in this case the prompt can match the others of the same code block, or default to $.
    • Do not add comments in the same box of a command, for example: 
      # pacman -S foo  #Install package foo
    • Avoid writing excessively long lines of code: use line-breaking techniques when possible.
  • Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).

File editing requests

  • Do not assume a specific text editor (nano, vim, emacs, etc.) when requesting text file edits, except when necessary.
  • Do not use implicit commands to request text file edits, unless strictly necessary. For example, $ echo -e "clear\nreset" >> ~/.bash_logout should be:
Append the following lines to ~/.bash_logout:
clear
reset

Keyboard keys

  • The standard way to represent keyboard keys in articles is using instances of Template:ic.
  • Letter keys should be represented in lower case: a. To represent upper-case letters, use Shift+a instead of Shift+A or A.
  • The correct way to represent key combinations makes use of the + symbol to join keys, with no additional spaces around it, in a single instance of the template: Ctrl+c.
    Ctrl + c, Ctrl+c, Ctrl-c are non-compliant forms, and should be avoided.
  • The correct way to represent key sequences is either verbose, e.g. "press g followed by Shift+t", or concise, separating the keys with a single space in different instances of the template: g Shift+t.
  • The following are the standard ways of representing some special keys:
    • Shift (not SHIFT)
    • Ctrl (not CTRL or Control)
    • Alt (not ALT)
    • Super (not Windows or Mod)
    • Enter (not ENTER or Return)
    • Esc (not ESC or Escape)
    • Space (not SPACE)
    • Backspace
    • Tab
    • Ins (not INS or Insert)
    • Del (not DEL or Delete)
    • PrintScreen
    • PageUp
    • PageDown

Notes, Warnings, Tips

  • A Note should be used for information that somehow diverges from what the user would naturally expect at some point in the article. This includes also information that gives more in-depth knowledge on something in particular that otherwise would be considered a bit extraneous to the article. Another example is when needing to point out a temporary announcement like a change in the name of a package.
A Note can also be used to highlight information that is important but easily overlooked by someone new to the subject area.
  • A Warning should be used where the described procedure could carry severe consequences such as being reasonably difficult to undo or resulting in damage to the system. Warnings should generally indicate both the worst case scenarios as well as the conditions that could lead to or avoid such worst cases.
In general, do not abuse Warnings: if you are undecided, chances are high that you should use a Note.
  • A Tip should indicate a method or procedure that could be useful and bring benefits to somebody, albeit not needed to complete the operation being dealt with, and therefore safely ignorable.
  • When two or more notes, warnings or tips have to appear one after each other at the same point of an article, prefer grouping their texts in a list inside a single template, avoiding stacking the templates unless they are completely unrelated. For example:
Tip:
  • Tip example #1.
  • Tip example #2.

Shells

  • Do not assume a particular shell as the user's shell (e.g. Bash), except when really needed: try to be as shell-neutral as possible when writing or editing articles.

Hypertext metaphor

  • Try to interlink your article with as many others as you can, using the various keywords in the text.
  • Only link to a new article after creating it. In general, do not create links to non-existent articles.
  • For technical terms, such as system call, not covered by an article in the wiki, link to the relevant Wikipedia page.
  • When linking to other articles of the wiki, do not use full URLs; take advantage of the special syntax for internal links: [[Wiki Article]]. This will also let the wiki engine keep track of the internal links, hence facilitating maintenance.
    See Help:Editing#Links for in-depth information and more advanced uses of interwiki links syntax.
  • Avoid implicit links whenever possible. For example, prefer instructions like "See the systemd article for more information" instead of "See here for more information".
  • Except in rare cases, you should not leave an article as a dead-end page (an article that does not link to any other) or an orphan page (an article that is not linked to from any other).
  • Before writing a specific procedure in an article or describing something in particular, always check if there is already an article that treats that part in detail: in that case, link that article instead of duplicating its content.

Coding style

  • When adding commands or scripts, use a consistent coding style throughout the article, possibly also referring to the other articles, especially if there are any related ones. If available, respect the official or most common coding style guidelines for the language.
  • Avoid deprecated features of the programming/scripting language you are using: for example, use the $() syntax for shell command substitution instead of the backticks/grave (``) syntax.

"Tips and tricks" sections

  • Tips and tricks sections provide advanced tips or examples of using the software.
  • Use the standard title of Tips and tricks.
  • The various tips and tricks should be organized in subsections.

"Troubleshooting" sections

  • Troubleshooting sections are used for frequently asked questions regarding the software or for solutions to common problems (compare to #"Known issues" sections).
  • Use the standard title of Troubleshooting. Common misspellings that should be avoided are Trouble shooting, Trouble-shooting, and TroubleShooting.
  • You can also report temporary workarounds for known bugs, but in this case, it is very desirable that you provide a link to the bug report. In case it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
    There are great benefits in linking to a bug report both for readers and editors:
    • For readers, the Wiki does not become a stopping point: they can find more information close to the source that may have otherwise been missed by their search efforts.
    • For Wiki editors, it makes cleanup easier by reducing the effort involved in researching whether the reported bug is still an issue; this can even lead to greater autonomy if the reader finds new information and comes back to edit the wiki.

"See also" sections

  • See also sections contain a list of links to references and sources of additional information.
  • This should be a list where each entry is started with *, which creates a MediaWiki bulleted list.
  • Use See also for internal and interwiki links only!
  • Place See also at the bottom of the page, just before categories.

Non-pertinent content

  • Please do not sign articles, nor credit article authors: the wiki is a work of the community, and the history of each article is enough for crediting its contributors.
    Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.

Category pages

  • Every category must be appropriately categorized under at least one parent category, except for root categories.
  • A category can be categorized under more than one category, provided one is not ancestor of the others.
  • Avoid circular relationships: two categories cannot be reciprocal ancestors.
  • Do not categorize a category under itself (self-categorized category).
  • Categories must be included at the bottom of the category page.
  • Categories should not redirect, except temporarily during renaming.
  • By default, category names should be in the singular form ("topic" categories); they should be in the plural form if the singular form can be used to describe one of its members ("set" categories).

Redirect pages

  • Redirect pages should contain only the redirect code and nothing else. In rare cases, they can also contain a flag such as Template:Delete.
  • Redirect only to internal articles; do not use interwiki redirections.

User pages

  • Pages in the User namespace cannot be categorized.
  • Pages in the User namespace can only be linked from other pages in the User or talk namespaces, unless authorization to do otherwise is given by Administrators.

Generic rules

Edit summary

See InstallGentoo Wiki:General rules

HTML tags

  • Usage of HTML tags is generally discouraged: always prefer using wiki markup or templates when possible, see Help:Editing and related.
  • When tempted to use <pre>code</pre>, always resort to {{bc|code}}. When tempted to use <tt>text</tt> or <code>text</code>, always resort to {{ic|text}}.
  • Especially avoid HTML comments (<!-- comment -->): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page.
    You can add an appropriate Article status template in place of the comment.
  • Use <br> only when necessary: to start a new paragraph or break a line, put a blank line below it.
    Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.

First person remarks

Avoid these words in a page: I, we, our, etc. Always use third-person remarks on any article. For guides, then you can use second-person remarks. However, you can use first-person remarks for section and sub-section titles (such as How should I write my article?).

This rule does NOT affect the talk page and user page.

See also

Retrieved from "https://igwiki.lyci.de/index.php?title=Help:Style&oldid=19970"