Difference between revisions of "Help:Style"
m (→Categories: fix indent)
m (→Interlanguage links: fix indent)
|Line 39:||Line 39:|
*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.
*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.
*See also [[Wikipedia:Help:Interlanguage links]].
*See also [[Wikipedia:Help:Interlanguage links]].
Revision as of 17:31, 22 September 2011
- 1 Article pages
- 1.1 Layout
- 1.2 Categories
- 1.3 i18n template
- 1.4 Interlanguage links
- 1.5 Article status templates
- 1.6 Article summary
- 1.7 Preface/Introduction
- 1.8 Table of Contents
- 1.9 Heading levels
- 1.10 Package management instructions
- 1.11 Daemon operations instructions
- 1.12 Command line text
- 1.13 File text
- 1.14 "Tips and tricks" sections
- 1.15 "Troubleshooting" sections
- 1.16 "Known issues" sections
- 1.17 "See also" sections
- 1.18 Non-pertinent content
- 2 Discussion pages
- 3 Category pages
- 4 Redirect pages
- 5 User pages
- 6 Generic rules
- i18n template
- Interlanguage links (optional)
- Article status templates (optional)
- Article summary (optional? disputed, see talk page)
- Table of Contents (automatic)
- 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.
- Template:i18n should be put on every article and category page, right below the categories.
- See also Help:i18n.
- 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.
- See also Wikipedia:Help:Interlanguage links.
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.
- Describes the structure and scope of the article.
- Included right below Template:i18n or Article status templates, if present.
- See also Writing Article Overviews.
- 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 a
==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.
- Headings should start from level 2 (
- Do not skip levels when making subsections, so a subsection of a level 2 needs a level 3 heading and so on.
- See Effective Use of Headers.
Package management instructions
Daemon operations instructions
Command line text
$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
# commandinstead of writing
$ sudo commandunless it is really necessary.
- Do not assume the user uses sudo or other privilege escalation utilities (e.g. gksu, kdesu).
# sudo commandis always wrong.
- Do not add comments in the same box of a command (e.g.
# pacman -S foo #Install package foo)
"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.
- 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, if it has not been reported yet, you should report it yourself, thus increasing the chances that the bug will be properly fixed.
"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.
- 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.
- 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.
- Discussion pages cannot be categorized.
- 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, Category:Template and Category:Website Resources.
- 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.
- 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).
- All edits to articles should be accompanied by some words in the summary field, answering the question "Why did you edit the article?". "What", "where", "when" and "how" are self-explained by the diff itself, it is redundant to add them.
- An explanation is not mandatory in talk pages, where the "why" should be already evident.
- Links are allowed in the summary field, so it is possible to point to an existing discussion.
- Avoid double blank lines as much as possible.
- Usage of HTML tags is generally discouraged.
- When tempted to use
<pre>code</pre>, assess the possibility to use space-initial lines or
- 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
- When tempted to use
<code>text</code>, always resort to
- 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.
<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.