Difference between revisions of "Help:Style"

From ArchWiki
Jump to: navigation, search
(starting to work here, hopefully a bit every day, the wiki needs definitive style rules at this point)
(Article structure: just starting to add content quite randomly, also the layout is probably temporary, feedback and contributions are welcome of course)
Line 17: Line 17:
 
}}
 
}}
 
__ToC__<!-- Temporarily forcing the ToC until it appears automatically -->
 
__ToC__<!-- Temporarily forcing the ToC until it appears automatically -->
==Article structure==
+
==Article layout==
 +
;Categories
 +
:Categories must be included at the top of every article and category (except for root categories).
 +
:{{Note|This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.}}
  
In terms of layout, articles on ArchWiki can be considered to consist of two components, the ''preface'' and the ''body''.
+
;i18n
 +
:[[Template:i18n]] should be put on every article and category page, right below the categories. See [[Help:i18n]].
  
; Preface: The ''preface'' is the portion of wikitext that precedes any headings. Information about the article contents, such as categories, [[Help:i18n|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.
+
;Article status templates
: {{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.}}
+
:As showed at the top of this page, [[:Category:Template#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.
  
; Body: The ''body'' is the remaining ''content'' of the article. Although pages vary from topic to topic, most articles follow this general outline:
+
;Article summary
 +
:This is used to describe the structure and scope of the article. See [[Writing Article Overviews]].
  
:; Introduction: A summary of what the article is to cover
+
;Preface/Introduction
:; Installation: If applicable, the instructions on how to install the software
+
:Describes the topic of the article.
:; Configuration: If applicable, how the software is configured once installed
+
:Do not explicitly make a {{Ic|1===Introduction==}} or {{Ic|1===Preface==}} section: this will let the introduction appear above the Table of Contents.
:; Tips and tricks: If applicable, advanced tips or examples of using the software
+
 
:; Troubleshooting: Frequently asked questions regarding the software
+
;Table of Contents
:; More resources: A list of references and sources of additional information
+
:The Table of Contents is shown automatically when there are sufficient sections in the article.
 +
 
 +
===Standard optional sections===
 +
;Installation
 +
:If applicable, contains the instructions on how to install the software.
 +
 
 +
;Configuration
 +
:If applicable, describes how the software is configured once installed.
 +
 
 +
;Tips and tricks
 +
:If applicable, contains advanced tips or examples of using the software.
 +
 
 +
;Troubleshooting
 +
:Frequently asked questions regarding the software, or solutions to common problems.
 +
:''Trouble shooting'', ''Trouble-shooting'', ''TroubleShooting'' are examples of common title mistakes; please use ''Troubleshooting'' consistently.
 +
 
 +
;See also
 +
:A list of links to references and sources of additional information.
 +
:This should be a list where each line is started with {{Ic|*}}.
 +
:The standard title is ''See also'', other similar titles like ''External links'', ''More resources'' etc. should be avoided.
 +
 
 +
===Non-compliant sections or content===
 +
;Credits
 +
: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.
 +
 
 +
==Article source code==
 +
;Heading levels
 +
:See [[Effective Use of Headers]].
 +
 
 +
;Blank lines
 +
:There should be no blank lines between categories, templates and the first line of text in the preface, because this introduces extra space at the top of the article.
 +
:Avoid double blank lines as much as possible.
 +
 
 +
;HTML comments
 +
:Avoid HTML comments ({{Ic|<nowiki><!-- comment --></nowiki>}}) as much as possible.
 +
:It is likely that a note added in a HTML comment can be explicitly shown in the discussion page of the article.
  
 
==Commands: regular user or root==
 
==Commands: regular user or root==

Revision as of 12:32, 17 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 layout

Categories
Categories must be included at the top of every article and category (except for root categories).
Note: This is different from some other MediaWiki projects such as Wikipedia, which include categories at the bottom.
i18n
Template:i18n should be put on every article and category page, right below the categories. See 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
This is used to describe the structure and scope of the article. See Writing Article Overviews.
Preface/Introduction
Describes the topic of the article.
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 when there are sufficient sections in the article.

Standard optional sections

Installation
If applicable, contains the instructions on how to install the software.
Configuration
If applicable, describes how the software is configured once installed.
Tips and tricks
If applicable, contains advanced tips or examples of using the software.
Troubleshooting
Frequently asked questions regarding the software, or solutions to common problems.
Trouble shooting, Trouble-shooting, TroubleShooting are examples of common title mistakes; please use Troubleshooting consistently.
See also
A list of links to references and sources of additional information.
This should be a list where each line is started with *.
The standard title is See also, other similar titles like External links, More resources etc. should be avoided.

Non-compliant sections or content

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

Article source code

Heading levels
See Effective Use of Headers.
Blank lines
There should be no blank lines between categories, templates and the first line of text in the preface, because this introduces extra space at the top of the article.
Avoid double blank lines as much as possible.
HTML comments
Avoid HTML comments (<!-- comment -->) as much as possible.
It is likely that a note added in a HTML comment can be explicitly shown in the discussion page of the article.

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