Difference between revisions of "Help:Style"

From ArchWiki
Jump to: navigation, search
m (got rid of multi-language category)
(starting to work here, hopefully a bit every day, the wiki needs definitive style rules at this point)
Line 1: Line 1:
 
[[Category:ArchWiki Help (English)]]
 
[[Category:ArchWiki Help (English)]]
 
[[Category:ArchWiki Tools]]
 
[[Category:ArchWiki Tools]]
<!--{{i18n|Help:Style}}-->
+
{{i18n|Help:Style}}
{{Stub}}
+
{{Stub}}<!-- This template is temporary, it's not meant to stay here when the page will be completed -->
 
+
{{Message_box
This page aims to provide a guide for the standardization of style in the articles of this wiki.
+
|id              = msgboxdemo
 
+
|signal          = [[Image:Tango-dialog-information.png]]
{{Note|
+
|heading        = This is a demonstration template.
*This guide is a draft, it has not been officialized yet, and its rules cannot be considered in a definitive status.
+
|message        = [[:Category:Template#Article_status_templates|Atricle status templates]] can be put at the top of an article right below the i18n bar and right above the preface/overview.}}
*You are warmly invited to discuss your additions or modifications in the [[Help_talk:Style|talk page]], before submitting them; you can also start discussions in the [https://bbs.archlinux.org/viewforum.php?id&#61;13 forum], but you should add a link to the thread in the talk page anyway.
+
{{Article summary start}}
 +
{{Article summary text|This page aims to provide a guide for the standardization of style in the articles of this wiki.}}
 +
{{Article summary heading|Related}}
 +
{{Article summary wiki|Help:Editing}}
 +
{{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 [[Help_talk:Style|talk page]], before submitting them; you can also start discussions in the [https://bbs.archlinux.org/viewforum.php?id&#61;13 forum], but you should add a link to the thread in the talk page anyway.
 
}}
 
}}
 
+
__ToC__<!-- Temporarily forcing the ToC until it appears automatically -->
 
==Article structure==
 
==Article structure==
  

Revision as of 11:37, 16 September 2011

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:Message box

Template:Article summary start Template:Article summary text Template:Article summary heading 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 structure

In terms of layout, articles on ArchWiki can be considered to consist of two components, the preface and the body.

Preface
The preface is the portion of wikitext that precedes any headings. Information about the article contents, such as categories, i18n and article status templates, and article overviews, should be kept at the top of all articles, in that order. Some articles include a brief introduction here, before any headings.
Note: Categories are included at the top of pages. This is different from some other MediaWiki projects such as Wikipedia which include them at the bottom. There should be no blank lines between the categories and article text, because this introduces extra space at the top of the article.
Body
The body is the remaining content of the article. Although pages vary from topic to topic, most articles follow this general outline:
Introduction
A summary of what the article is to cover
Installation
If applicable, the instructions on how to install the software
Configuration
If applicable, how the software is configured once installed
Tips and tricks
If applicable, advanced tips or examples of using the software
Troubleshooting
Frequently asked questions regarding the software
More resources
A list of references and sources of additional information

Commands: regular user or root

When writing CLI commands, always make distinction whether each should be issued as a regular user, or as root:

  • use $ for regular user commands:

Template:Cli

  • use # for root commands:

Template:Cli

Prefer using this method 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.

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 (and ending the sentence with a colon, like in the examples above).