Difference between revisions of "Help:Style"

From ArchWiki
Jump to: navigation, search
m (improve rule, move (back) to better-suited place)
(improve layout, add some more rules)
Line 8: Line 8:
 
|heading        = This is a demonstration template.
 
|heading        = This is a demonstration template.
 
|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.}}
 
|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.}}
 +
 
{{Article summary start}}
 
{{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 text|This page aims to provide a guide for the standardization of style in the articles of this wiki.}}
Line 13: Line 14:
 
{{Article summary wiki|Help:Editing}}
 
{{Article summary wiki|Help:Editing}}
 
{{Article summary end}}
 
{{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.
 
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=13 forum], but you should add a link to the thread in the talk page anyway.
 
{{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=13 forum], but you should add a link to the thread in the talk page anyway.
 
}}
 
}}
==Article layout==
+
 
;Categories
+
==Article pages==
:Categories must be included at the top of every article and category (except for root categories).
+
 
 +
===Layout===
 +
#[[#Categories|Categories]]
 +
#[[#i18n template|i18n]]
 +
#[[#Article status templates|Article status templates]] (optional)
 +
#[[#Article summary|Article summary]] (optional? disputed, [[Help_talk:Style#Article_summary_templates|see talk page]])
 +
#[[#Preface/Introduction|Preface/Introduction]]
 +
#[[#Table of Contents|Table of Contents]] (shown automatically when article has sufficient sections)
 +
#[[#Standard optional sections|Various article sections]]
 +
 
 +
===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.}}
 
:{{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.
+
*There should be no blank lines between categories and the i18n bar, because this introduces extra space at the top of the article.
  
;i18n
+
===i18n template===
:[[Template:i18n]] should be put on every article and category page, right below the categories. See [[Help:i18n]].
+
*[[Template:i18n]] should be put on every article and category page, right below the categories.
 +
*See also [[Help:i18n]].
  
;Article status templates
+
===Article status templates===
: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.
+
*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.
+
*Article status templates can also be used inside article sections, when appropriate.
  
;Article summary
+
===Article summary===
:This is used to describe the structure and scope of the article. See [[Writing Article Overviews]].
+
*Describes the structure and scope of the article.
 +
*Included right below [[Template:i18n]] or Article status templates, if present.
 +
*See also [[Writing Article Overviews]].
  
;Preface/Introduction
+
===Preface/Introduction===
:Describes the topic of the article.
+
*Describes the topic of the article.
:Do not explicitly make a {{Ic|1===Introduction==}} or {{Ic|1===Preface==}} section: this will let the introduction appear above the Table of Contents.
+
*Included right below the Article summary.
 +
*Do not explicitly make a {{Ic|1===Introduction==}} or {{Ic|1===Preface==}} section: this will let the introduction appear above the Table of Contents.
  
;Table of Contents
+
===Table of Contents===
:The Table of Contents is shown automatically when there are sufficient sections in the article.
+
*The Table of Contents is shown automatically below the Introduction when there are sufficient sections in the article.
  
 
===Standard optional sections===
 
===Standard optional sections===
;Installation
 
:If applicable, contains the instructions on how to install the software.
 
  
;Configuration
+
====Installation====
:If applicable, describes how the software is configured once installed.
+
*Instructions on how to install the software.
  
;Tips and tricks
+
====Configuration====
:If applicable, contains advanced tips or examples of using the software.
+
*Describes how the software is configured once installed.
  
;Troubleshooting
+
====Tips and tricks====
:Frequently asked questions regarding the software, or solutions to common problems.
+
*Advanced tips or examples of using the software.
:''Trouble shooting'', ''Trouble-shooting'', ''TroubleShooting'' are examples of common title mistakes; please use ''Troubleshooting'' consistently.
 
  
;See also
+
====Troubleshooting====
:A list of links to references and sources of additional information.
+
*Frequently asked questions regarding the software, or solutions to common problems.
:This should be a list where each line is started with {{Ic|*}}.
+
*''Trouble shooting'', ''Trouble-shooting'', ''TroubleShooting'' are examples of common title mistakes; please use ''Troubleshooting'' consistently.
:The standard title is ''See also'', other similar titles like ''External links'', ''More resources'' etc. should be avoided.
 
  
===Non-compliant sections or content===
+
====See also====
;Credits
+
*A list of links to references and sources of additional information.
: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.
+
*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.
  
==Article source code==
+
===Non-pertinent content===
;Heading levels
 
:See [[Effective Use of Headers]].
 
  
;Blank lines
+
====Credits and signatures====
:Avoid double blank lines as much as possible.
+
*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.
  
;HTML comments
+
==Discussion pages==
:Avoid HTML comments ({{Ic|<nowiki><!-- comment --></nowiki>}}) as much as possible.
+
{{Expansion}}
: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==
+
==Category pages==
When writing CLI commands, always make distinction whether each should be issued as a regular user, or as root:
+
{{Expansion}}
*use {{Ic|$}} for regular user commands:
+
 
$ makepkg -s
+
==Redirect pages==
*use <tt>#</tt> for root commands:
+
*Should contain only the redirect code, nothing more
# pacman -S kernel26
+
 
 +
==User pages==
 +
*Cannot be categorized (this rule can be infringed in very rare, admin-approved cases)
 +
 
 +
==Generic rules==
 +
 
 +
===Page markup/markdown===
 +
 
 +
====Heading levels====
 +
*Headings should start from level 2 ({{Ic|1===}}).
 +
*See [[Effective Use of Headers]].
  
Prefer using this method instead of writing {{Ic|$ sudo command}} unless it is really necessary. Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).
+
====Blank lines====
 +
*Avoid double blank lines as much as possible.
  
{{Ic|# sudo command}} is always wrong.
+
====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.
  
{{Note|Since {{Ic|#}} 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).}}
+
===Command line text===
 +
*use {{Ic|$}} for regular user commands:
 +
:<pre>$ makepkg -s</pre>
 +
*use {{Ic|#}} for root commands:
 +
:<pre># pacman -S kernel26</pre>
 +
:{{Note|Since {{Ic|#}} 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).}}
 +
*Prefer using {{Ic|# command}} instead of writing {{Ic|$ sudo command}} unless it is really necessary.
 +
*Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).
 +
*{{Ic|# sudo command}} is always wrong.
 +
*Do not add comments in the same box of a command (e.g. {{Ic|# pacman -S foo  #Install package foo}})

Revision as of 10:54, 18 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 – فارسی

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 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 (shown automatically when article has sufficient sections)
  7. Various article sections

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

Standard optional sections

Installation

  • Instructions on how to install the software.

Configuration

  • Describes how the software is configured once installed.

Tips and tricks

  • 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-pertinent content

Credits and signatures

  • 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

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

Category pages

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

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

Page markup/markdown

Heading levels

Blank lines

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

Command line text

  • use $ for regular user commands:
$ makepkg -s
  • use # for root commands:
# pacman -S kernel26
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).
  • 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)