Help:Style

From ArchWiki
Revision as of 13:27, 19 September 2011 by Kynikos (talk | contribs) (add content)
Jump to: navigation, 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 – فارسی

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: please use the first argument of the template to provide more detailed indications. (Discuss in Help talk:Style#)
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: You are warmly invited to discuss your additions or modifications to this page in the talk page, before submitting them; you can also start discussions in the forum, but you should add a link to the thread in the talk page anyway.

Article pages

Layout

  1. Categories
  2. i18n
  3. Article status templates (optional)
  4. Article summary (optional? disputed, see talk page)
  5. Preface/Introduction
  6. Table of Contents (automatic)
  7. Article-specific sections

Categories

  • Every article must be categorized under at least 1 existing category.
  • If categorizing under more than 1 category, make sure that none of those categories is an 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.

i18n template

  • Template:i18n should be put on every article and category page, right below the categories.
  • See also Help:i18n.

Article status templates

  • As showed at the top of this page, 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/Introduction

  • Describes the topic of the article.
  • Included right below the Article summary.
  • Do not explicitly make a ==Introduction== or ==Preface== section: this will let the introduction appear above the Table of Contents.

Table of Contents

  • The Table of Contents is shown automatically below the Introduction when there are sufficient sections in the article.

Heading levels

Package management instructions

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: please use the first argument of the template to provide a brief explanation. (Discuss in Help talk:Style#)

Daemon operations instructions

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: please use the first argument of the template to provide a brief explanation. (Discuss in Help talk:Style#)

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)

File text

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: please use the first argument of the template to provide a brief explanation. (Discuss in Help talk:Style#)

"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.
  • Standard title is Troubleshooting: Trouble shooting, Trouble-shooting, TroubleShooting are common mistake examples.

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

Discussion pages

  • Add new discussions at the bottom of discussion pages and with a proper heading.
  • Indent your answers using colons at the beginning of new lines.
  • Always append a signature to your edits.

Category pages

  • Every category must be categorized under at least 1 parent category, except for root categories.
Root categories are language categories, like Category:English and some other special categories: Category:DeveloperWiki, Category:DeveloperWiki:Server Configuration, Category:Sandbox, Category:Template and Category:Website Resources.
  • If categorizing under more than 1 category, make sure that none of those categories is an ancestor of the others.
  • Categories must be included at the top of the category page.

Redirect pages

  • Should contain only the redirect code, nothing more

User pages

  • Cannot be categorized (this rule can be infringed in very rare, admin-approved cases)

Generic rules

Line breaks

  • Avoid double blank lines as much as possible.

HTML tags

  • Usage of HTML tags is generally discouraged.
  • When tempted to use <pre>code</pre>, assess the possibility to use space-initial lines or {{Bc|code}} (see Help:Editing).
Exceptions to this rule can be made when trying to put some code in a list, or when trying to indent it: in both cases, however, see if you can use {{Ic|code}} instead.
  • 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.
  • Use <br> only when necessary: to start a new paragraph or break a line, put a blank line below it.
A common exception to this rule is when it is necessary to break a line inside a template and you cannot use a list.