Difference between revisions of "Help:Editing"

From ArchWiki
Jump to: navigation, search
m (Editing: wc)
m (Tone, layout, and style: em, wording)
Line 48: Line 48:
 
:; More resources: ''A list of references and sources of additional information''
 
:; More resources: ''A list of references and sources of additional information''
  
:Individual subheadings can and ''should'' be used ''under'' each of these main headings. See [[#Headings and subheadings]] below. This is a general guideline, feel free to deviate where appropriate.
+
:Individual subheadings can and should be used under each of these main headings. See [[#Headings and subheadings]] below. This is simply a guideline, feel free to deviate where appropriate.
  
 
While writing, remember not only to answer ''how?'' and ''what?'', but also  ''why?'' Explanatory information always goes further toward imparting knowledge than does instruction alone.
 
While writing, remember not only to answer ''how?'' and ''what?'', but also  ''why?'' Explanatory information always goes further toward imparting knowledge than does instruction alone.

Revision as of 17:40, 19 March 2010

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:Moveto

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary end

This is a short tutorial about editing the ArchWiki; for more detail, please see Help:Editing. To experiment with editing, please use the Sandbox.

Overview

ArchWiki is a community documentation process. The contents are created by the community for the community.

Wikis, by design, thrive on collaboration. Contributors volunteer their time and energy to share their knowledge and skill with the community. All users are encouraged to contribute. Tasks on ArchWiki can roughly be divided into the following:

  • Technical maintenance
  • Content management
  • Content editing
  • Content creation and translation

Please see AboutWiki for more information.

ArchWiki is powered by MediaWiki, a free software wiki package written in PHP, originally for use on Wikipedia. More in-depth help can be found at Help:Contents on MediaWiki and Help:Contents on Wikipedia.

Before editing or creating pages, users are encouraged to familiarize themselves with the general tone, style, and layout of existing articles. An effort should be made to maintain a level of consistency throughout the wiki.

Tone, layout, and style

In general, language should be concise and professional. Write objectively; avoid personal opinions. Whenever possible, link to existing articles and resources; avoid duplication of effort.

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. Metadata, 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.
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
Individual subheadings can and should be used under each of these main headings. See #Headings and subheadings below. This is simply a guideline, feel free to deviate where appropriate.

While writing, remember not only to answer how? and what?, but also why? Explanatory information always goes further toward imparting knowledge than does instruction alone.

See Help:Reading for an overview of common stylistic conventions. Further details are provided in the sections that follow.

Editing

You must be logged-in to edit pages. Visit Special:UserLogin to log in or create an account. Your changes will be visible immediately. Just click the edit link that appears at the top of every page.

Explain your edit in the Summary box between the edit window and the save and preview buttons (e.g. "typo" or "added info on xyz").

Use the Show preview button to check your edit and get the formatting right before saving. Remember to save your edits before moving on by clicking Save page.

If you are logged in, you can mark an edit as "minor" by checking the This is a minor edit box to let people know your edit is not something substantive.

To try editing, open a new window and go to the Sandbox (which is an editing test area), and then click the edit link. Add something and click save.

Note: Articles should not be signed because they are shared works; one editor should not be singled out above others.

Reverting edits

If a page was edited incorrectly, the following procedures describe how to revert an article to a previous version. To revert a single edit:

  1. Click the history tab at the top of the page to be modified (beside the edit tab). A list of revisions is displayed.
  2. Click the undo link to the right of the offending edit. An edit preview is displayed, showing the current revision on the left and the text to be saved on the right.
  3. If satisfied, click the Save page button at the bottom of the page.

The wiki page should now be back in its original state.

Occasionally, it is necessary to revert several edits at once. To revert an article to a previous version:

  1. Click the history tab at the top of the page to be modified (beside the edit tab). A list of revisions is displayed.
  2. View the desired revision (i.e. the last good version) by clicking on the appropriate timestamp. That revision is displayed.
  3. If satisfied, click the edit tab at the top of the page. A warning is displayed: You are editing an out-of-date revision of this page. Simply click the Save page button to revert to this version.

Avoid combining an undo and an edit! Revert the edit first, then make additional changes; do not edit the revision preview.

Creating pages

Before creating a new page, please consider the following:

  1. Is your topic relevant to Arch Linux? Irrelevant or unhelpful articles will be deleted.
  2. Is your topic of interest to others? Consider not only what you wish to write about, but also what others may wish to read. Personal notes belong on your user page.
  3. Is your topic worthy of a new page? Search the wiki for similar articles. If they exist, consider improving or adding a section to an existing article instead.
  4. Will your contribution be significant? Avoid creating stubs unless planning to expand them shortly thereafter.

Creating a new page requires selection of a descriptive title and an appropriate category.

Please read Article Naming Guidelines and Writing Short Article Names for article naming advice.

  1. Titles should be capitalized appropriately: Title for New Page; not Title for new page.
  2. Do not include "Arch Linux" or variations in page titles. This is the Arch Linux wiki; it is assumed that articles will be related to Arch Linux. (e.g., Installing Openbox; not Installing Openbox in Arch Linux).

Visit the Table of Contents to help choose an appropriate category. Articles may belong to multiple categories.

To add a new page to some category (say "My New Page" to "Some Category") you need to:

  1. Create a page with your new title by browsing to http://wiki.archlinux.org/index.php/My_New_Page
  2. Add [[Category:Some Category]] to the top of your page

Formatting

Text formatting is accomplished with wiki markup whenever possible; learning HTML is not necessary. Various templates are also available for common formatting tasks; see Help:Template for information about templates.

Bold and italics

Bold and italics are added by surrounding a word or phrase with multiple apostrophes ('):

  • ''italics'' is rendered as italics (2 apostrophes on either side)
  • '''bold''' is rendered as bold (3 apostrophes on either side)
  • '''''bolded italics''''' is rendered as bolded italics (2 + 3 = 5 apostrophes on either side)

Headings and subheadings

Headings and subheadings are an easy way to improve the organization of an article. If you can see two or more distinct topics being discussed, you can break up your article by inserting a heading for each section. Please read Effective Use of Headers HOWTO for more information.

Headings can be created like this:

==First-level heading==
===Second-level heading===
====Third-level heading====
=====Fourth-level heading=====

Headings use sentence case; not title case: My new heading; not My New Heading.

Headings should not skip levels. That is, do not use a third-level heading before first using a second-level heading.

If an article has at least three headings, a table of contents (TOC) will be automatically generated. If this is not desired, place __NOTOC__ in the article. Try creating some headings in the Sandbox and see the effect on the TOC.

Indenting

To indent text, place a colon (:) at the beginning of a line. The more colons you put, the further indented the text will be. A newline (pressing Enter or Return) marks the end of the indented paragraph.

For example:

This is aligned all the way to the left.
:This is indented slightly.
::This is indented more.

...is shown as:

This is aligned all the way to the left.

This is indented slightly.
This is indented more.

Bullet points

To insert a bullet, use an asterisk (*). Similar to indentation, more asterisks in front of a paragraph means more indentation.

For example:

* First list item
* Second list item
** Sub-list item under second
* Isn't this fun?

...is shown as:

  • First list item
  • Second list item
    • Sub-list item under second
  • Isn't this fun?

Numbered lists

You can also create numbered lists. For this, use the number sign or hash symbol (#). Using more #s will affect the level of indenting.

For example:

# First item 
# Second item 
## Sub-item under second item 
# Third item 

...is shown as:

  1. First item
  2. Second item
    1. Sub-item under second item
  3. Third item

Definition lists

Definition lists are defined with a leading semicolon (;) and a colon (:) following the term.

For example:

; Apple: Fruit with red or yellow or green skin and sweet to tart crisp whitish flesh
; Banana: Elongated crescent-shaped yellow fruit with soft sweet flesh

...is shown as:

Apple
Fruit with red or yellow or green skin and sweet to tart crisp whitish flesh
Banana
Elongated crescent-shaped yellow fruit with soft sweet flesh

Use additional colons if a definition spans multiple lines.

For example:

; Term: First line of definition
: Second line of definition
: Third line of definition

...is shown as:

Term
First line of definition
Second line of definition
Third line of definition

Code

To add code to the wiki, simply start each line with a single whitespace character. However, be careful of the length of your text lines as the text will not automatically wrap to fit the screen.

Alternatively, use <pre> tags, or one of the available code formatting templates.

For example:

<pre>
#!/bin/bash
# sample code
</pre>

...is shown as:

#!/bin/bash
# sample code

Links

Links are important on wikis to help readers navigate the site.

Internal links

You can extensively cross-reference wiki pages using internal links. You can add links to existing titles, and also to titles you think ought to exist in future.

To make a link to another page on the same wiki, just put the title in double square brackets.

For example, if you want to make a link to, say, the Wikia page, use:

[[Wikia]]

If you want to use words other than the article title as the text of the link, you can add an alternative name after the pipe "|" divider (Template:Keypress + Template:Keypress on English-layout and similar keyboards).

For example:

View the [[Arch Linux|home page]]...

...is shown as:

View the home page...

When you want to use the plural of an article title (or add any other suffix) for your link, you can add the extra letters directly outside the double square brackets.

For example:

makepkg is used in conjunction with [[PKGBUILD]]s.

...is shown as:

makepkg is used in conjunction with PKGBUILDs.

Links to sections of a document

To create a link to a section of a document, simply add a # followed by the section's heading.

For example:

[[ArchWiki Tutorial#Links to sections of a document]]

...is shown as:

ArchWiki Tutorial#Links to sections of a document
Tip: Do not needlessly reformat section links (e.g. [[#Links to sections of a document|Links to sections of a document]]). If linking to a section within the same page, the page name can be omitted (e.g. [[#Links to sections of a document]]).

Interlanguage links

The ArchWiki is international; articles may be written in multiple languages. If an article exists in more than one language, Template:i18n may be added to the article to display links to available translations.

To use this template in an article, add at the beginning of the article:

{{i18n|Title in English}}

See Help:i18n for detailed information about ArchWiki internationalization and localization.

Interwiki links

So-called interwiki links can be used to easily link to articles in other external Wikis, like Wikipedia for example. The syntax for for this link type is the wiki name followed by a colon and the article you want to link to enclosed in double square brackets.

If you want to link to the Wikipedia:Arch Linux article you can use the following:

[[Wikipedia:Arch Linux]]

Or you can create a piped link with an alternate link label to the Arch Linux Wikipedia article:

[[Wikipedia:Arch Linux|Arch Linux Wikipedia article]]
Note: Using a piped link with an alternative link label should be reserved for abbreviating longer URLs.

See: Wikipedia:InterWikimedia links

External links

If you want to link to an external site, just type the full URL for the page you want to link to.

http://www.google.com/

It is often more useful to make the link display something other than the URL, so use one square bracket at each end, with the alternative title after the address separated by a space (not a pipe). So if you want the link to appear as Google search engine, just type:

[http://www.google.com/ Google search engine]

Redirects

To redirect automatically from one page to another, type #REDIRECT and then put in brackets the name of the page to be redirected to.

For example, you could redirect from "Cats" to "Cat":

#REDIRECT [[Cat]]

That way, anyone typing either version in the search box will automatically go to "Cat".

Wiki variables, magic words, and templates

MediaWiki recognizes certain special strings within an article to aid in formatting and alter standard behaviors. For example, use {{SITENAME}} to display the wiki's site name (which, on this wiki, is: ArchWiki). See Help:Magic words for details.

You can also create your own templates. After you create the page Template:XXX, using the command {{XXX}} will include that content in your current page. So, if you have something that needs to be included on many other pages, you might want to use a template.

See Help:Template for more information.

Discussion pages

Discussion or "talk" pages are for communicating with other ArchWiki users.

To discuss any page, go to that page and then click the "discussion" tab at the top of the page. Add a new comment at the end of the page or reply below an existing comment. Use indenting to format your discussion. Standard practice is to indent your reply one more level deep than the person to whom you are replying. Further, you should insert your comment beneath the one to which you are replying, but below others who are doing the same.

Sign comments by typing ~~~~ to insert your username and a timestamp. Avoid editing another user's commments.

Experiment by editing the talk page of the Sandbox.

User talk pages

Note the difference between a user page, and a user talk page. Everyone may have a user talk page on which other people can leave public messages. If one does not exist for a particular user, you may create it so that you can leave a comment. If someone has left you a message on yours, you will see a note saying "You have new messages" with a link to your own user talk page.

You can add comments on the user talk page of the person you're replying to or on your own talk page beneath the original message with appropriate indentation. If you reply on their talk page, they will receive notification of it.

Do not edit a user's own page without permission (i.e. [[User:Name]]); these serve as personal user spaces. The "user talk page" is the correct place for communicating (other than sending private email if the address is published).

Requests and special categories

Requests for specific articles or improvements to existing articles can be added to the Requests wiki page.

There also exist several special request categories to facilitate ArchWiki maintenance:

Visit these category pages for details.

See also