From ArchWiki
Revision as of 11:32, 16 October 2011 by Kynikos (talk | contribs) (Code formatting templates: do not bias voting while the poll is open)
Jump to navigation Jump to search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

One of the best ways to make sure that the information contained in a documentation medium is clear and easily understandable by all its users, is the compliance of its content with a series of conventional style rules. The ArchWiki is no exception to this concept: not only the article text must be coherent, as exhaustive as possible and written using formal style, but it must also appear tidily organized to the eye, being visually consistent with all the other articles. That is why all ArchWiki contributors are invited to follow these guidelines when editing articles.

Note: This guide has not been made official yet and its rules cannot be considered in a definitive status: please express your opinions in the talk page.

Article pages


  • 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 brackets) in the title: if you think both are commonly used, create a redirect for the acronym that points to the page titled with the expanded name.
  • See also Article Naming Guidelines.


  • The various elements of an article should be included in the following order:
  1. Categories
  2. i18n template
  3. Interlanguage links (optional)
  4. Article status templates (optional)
  5. Article summary (optional)
  6. Preface or introduction
  7. Table of contents (automatic)
  8. Article-specific sections


  • 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 top of every article.
    Note: This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.
  • There should be no blank lines between categories and the i18n bar, because this introduces extra space at the top of the article.
  • See also Recategorizing Pages.

i18n template

Interlanguage links

  • If the article has correspondence with one of the other external Arch Linux wikis in other languages, interlanguage links can be included right below the i18n template.
    Note that they will actually appear in the appropriate column to the left side of the page.
  • When adding or editing interlanguage links you should take care of repeating your action for all the translations of the article which are accessible in the i18n bar.
  • See also Wikipedia:Help:Interlanguage links.

Article status templates

  • Article status templates can be included right below Template:i18n and right above the Article Summary.
  • Article status templates can also be used inside article sections, when appropriate.

Article summary

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. An example is MediaTomb.
  • Included right below the Article summary.
  • 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.
  • See also Writing Article Introductions.

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.
  • See Effective Use of Headers.

Blank lines

  • Avoid double blank lines as much as possible.

Code formatting templates

  • Use {{ic|code}} for short lines of code, file names, command names, variable names and the like to be represented inline, for example:
    foo code bar.
  • Use {{bc|code}} for single or multiple lines of code (file content and command line input or output code) to be represented in a proper frame, for example:
# iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0

# Demo
echo "Hello World"
  • For short lines of code, you can just start them with a space instead of using {{bc|code}} (see Help:Editing), but note that the resulting code block will not add a horizontal scrollbar if code overflows from the screen: keep in mind that some readers may use a narrower screen than yours, or just keep the browser in a non-maximized window, so they could see the code overflowing even if you do not.
Note: A poll is open to make a decision about the remaining usages.

Command line text

  • Use $ as a prompt for regular user commands; use # as a prompt for root commands.
    Note: Since # 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 should usually end with :.
  • Prefer using # command instead of writing $ sudo command unless it is really necessary.
  • Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).
  • # sudo command is always wrong.
  • Do not add comments in the same box of a command (e.g. # pacman -S foo #Install package foo)
  • Avoid writing excessively long lines of code: use line-breaking techniques when possible.

File editing requests

  • Do not assume a specific text editor (nano, vim, emacs....) 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 better be:
Append the following lines to ~/.bash_logout:

Package management instructions

Official packages

  • The proper way to instruct for the installation of an official package is using a simple wording similar to the following:
    Install package, available in the Official Repositories.
    whose source code is [[pacman|Install]] {{Pkg|package}}, available in the [[Official Repositories]].
    The instructions for the installation of a list of packages may appear as:
    Install package1, package2 and package3, available in the Official Repositories.
    More basic phrasing examples may be:
    MyApplication can be installed with the package my-appplication, available in the Official Repositories.
    You can install MyApplication with the package my-appplication, available in the Official Repositories.
    You are granted the flexibility to adapt the wording to your specific article.
  • If the package is hosted in [core], [extra] or [community], making reference to the repository is discouraged, since it is not uncommon for a package to be moved to a different repository, and this would make the article maintenance more difficult. If however the package is hosted in an official repository which is not enabled by default (e.g. [multilib]), mentioning it is preferable.
  • Giving an example of the pacman command needed for the installation is deprecated, both for simplicity's sake (every Arch user should know pacman's article by memory) and to avoid errors such as pacman -Sy package or possibly never-ending discussions like the choice between pacman -S package and pacman -Syu package.
    All the more reason you should not suggest the use of pacman frontends or wrappers to install official packages.

AUR packages

  • The proper way to instruct for the installation of an AUR package is using a wording similar to the following:
    Install packageAUR, available in the Arch User Repository.
    whose source code is Install {{AUR|package}}, available in the [[Arch User Repository]].
    You are granted the flexibility to adapt the wording to your specific article, although you should always make clear that the package is unofficial.
  • Do not give examples on how to install AUR packages, neither with the official method nor mentioning AUR helpers: every user who installs unofficial packages should have read the Arch User Repository article, and be aware of all the possible consequences on his system.

Kernel module operations

  • Giving examples of how to add modules to the MODULES array in /etc/rc.conf is deprecated: the standard phrasing is a simple list of the modules involved, possibly remarking dependencies or conflicts with other modules, and a link to Kernel modules.
  • Giving examples of how to load, remove, blacklist or perform any other basic operation with modules is deprecated: the standard phrasing is a description of the actions to be performed, and a link to Kernel modules.

Daemon operations

  • Giving examples of how to add daemons to the DAEMONS array in /etc/rc.conf is deprecated: the standard phrasing is a simple list of the daemons involved, possibly remarking dependencies or conflicts with other daemons, and a link to Daemon.
  • Giving examples of how to start, restart or stop daemons is deprecated: the standard phrasing is a description of the actions to be performed, and a link to Daemon.
    Nevertheless, if the requested action is not one of those, an example is acceptable, and it should make use of the rc.d command instead of using the full /etc/rc.d/daemon command path.

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 information 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.
  • 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 example #1.
  • Tip example #2.


  • 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.
  • For technical terms like system call not covered by an article in the ArchWiki, link to the relevant Wikipedia page.
  • When linking to other articles of the wiki do not use full URLs, but take advantage of the special syntax for interwiki 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.
  • 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 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.
  • If the upstream documentation for the subject of your article is well-written and maintained, prefer just writing Arch-specific adaptations and linking to the official documentation for general information.

"Tips and tricks" sections

  • Advanced tips or examples of using the software.
  • Standard title is Tips and tricks.
  • The various tips and tricks should be organized in subsections.

"Troubleshooting" sections

  • Frequently asked questions regarding the software, or solutions to common problems (compare to #"Known issues" sections).
  • Standard title is Troubleshooting; Trouble shooting, Trouble-shooting, TroubleShooting are common mistake examples.
  • 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, and 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 clean up 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.

"Known issues" sections

  • Known bugs or usage problems which do not have a solution yet (compare to #"Troubleshooting" sections).
  • Standard title is Known issues.
  • If a bug report exists for the known issue, it is very desirable that you provide a link to it; otherwise, if it does not exist, you should report it yourself, thus increasing the chances that the bug will be fixed.

"See also" sections

  • A list of links to references and sources of additional information.
  • This should be a list where each entry is started with *.
  • The standard title is See also, other similar titles like External links, More resources etc. should be avoided.

Non-pertinent content

  • Please do not sign articles, nor credit article authors: the ArchWiki 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.

Language register

  • Articles should be written using a formal language register.
  • Avoid contractions, e.g. "don't", "isn't", "you've" etc. should be "do not", "is not", "you have".
  • Avoid unnecessary shortening of words: for example instead of "repo", "distro", and "config", prefer "repository", "distribution", and "configuration".
  • Do not include personal comments on articles, use discussion pages for this purpose. Do not write in first person in general.

Discussion pages

  • Add new discussions at the bottom of discussion pages and with a proper heading. You can also make use of the + tag at the top of each discussion page.
  • Indent your answers using colons at the beginning of new lines.
  • Always append a signature to your edits.
  • Discussion pages cannot be categorized.
  • You should take care to strike the header of exhausted discussions using <s> tags.
    Exhausted discussions will be deleted a while after striking.

Category pages

  • Every category must be categorized under at least one parent category, except for root categories.
    Root categories are language categories, like Category:English and some other special categories: Category:DeveloperWiki, Category:Sandbox and Category:Template.
  • 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.
  • Categories must be included at the top of the category page.
  • Categories should not redirect.

Redirect pages

  • Redirect pages should contain only the redirect code, nothing more.

Template pages

User pages

  • User pages cannot be categorized (this rule can be infringed in very rare, admin-approved cases).

Generic rules

Edit summary

  • The changes made daily to the articles are bravely checked by dedicated and voluntary patrollers, whom you must help by making sure that all your edits are accompanied by some explanation words in the "Summary" field of the editor page.
    • If the edit is minor, e.g. grammar or orthography corrections or the simple rewording of a sentence, a simple description of your edit is perfectly enough.
    • If you are performing a major change, e.g. adding, moving, modifying or removing content, besides summarizing your edit, you should make sure to explain the reason why you edited the article, even linking to a discussion on the wiki or the forums, if one exists at all.
    • An explanation is not mandatory in talk pages, where the why should be already evident.
      When deleting exhausted discussions, however, some explanation words are required (e.g. "closed discussion", "fixed" etc.), and including also the title of the discussion could help retrieving it in the history in case it needs to be reopened.
Tip: Take a look at the edit summaries in the Recent Changes to get an idea of what you should write in your summary, but be warned that unfortunately not all users respect these guidelines.
  • When performing major changes to articles, you should better try to split your work in multiple edits, based on the logical steps needed to complete the change.

HTML tags

  • Usage of HTML tags is generally discouraged: always prefer using wiki markdown 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.