Difference between revisions of "Writing Article Overviews"

From ArchWiki
Jump to: navigation, search
m (Formatting)
Line 1: Line 1:
 
[[Category: ArchWiki Help (English)]]
 
[[Category: ArchWiki Help (English)]]
 +
{{moveto|Writing article overviews}}
 
{{Article summary start}}
 
{{Article summary start}}
 
{{Article summary text|This article discusses article overview writing techniques. Article overviews are short textual summaries that appear inside a box on the right. This article covers some style questions, writing tips, and formatting techniques.}}
 
{{Article summary text|This article discusses article overview writing techniques. Article overviews are short textual summaries that appear inside a box on the right. This article covers some style questions, writing tips, and formatting techniques.}}

Revision as of 03:33, 18 December 2009

Template:Moveto Template:Article summary start Template:Article summary text Template:Article summary heading Template:I18n entry Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary wiki Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

This article was written to assist wiki writers and editors in creating effective articles and expand the ArchWiki readers' experience.

You are not required to know how to edit a wiki page in order to follow this article. This page is a more general style guide, rather than a technical editing HOWTO.

Article overview

When a reader first encounters the page, the first thing he or she notices is the article overview. Therefore, an overview has the task of quickly identifying the topic for the readers. It also presents readers with basic information about an article, such as available translations, required software, required hardware, related articles, etc.

The text

An effective article is one that fulfills its intended purpose. In order to fulfil its purpose, an article must introduce a method. You make your article effective by clearly defining the methods and the purpose.

Thus, an article overview needs to answer these two questions:

  1. What will I be able to achieve after I read this article?
  2. How will I achieve the goal?

The text should not be long. Two well thought out sentences, three at most.

Example

For example, this article has a three-sentence overview.

  • Answer to first question: This article discusses article overview writing techniques.
  • For some people, that may still not be enough information, so: Article overviews are short textual summaries that appear just below the article title.
  • Answer to second question: This article covers some style questions, writing tips, and formatting techniques.

As you can see, you don't need lengthy explanations of what are you going to talk about. However, you also need something people can read, before they really dig in.

This article's title may have easily been mistaken for a long list of summaries of all ArchWiki articles. Fortunately, thanks to the overvew, you do get a clear idea of what this article is about, even before reaching the first header.

Formatting

Article overviews are formatted using a set of templates. The templates are:

The Article summary start and Article summary end are mandatory. Of course, in order for the overview box to be of any use, you also need at least one Article summary text template.

Here is an example of a simple article overview box with just a summary text:

{{Article summary start}}
{{Article summary text|This is a short summary}}
{{Article summary end}}

Try it out in the Sandbox. Just copy the code above and copy it there. Preview or save the page to see the results.

It is recommended that the minimal article overview box contains the article summary and available languages.

The code to list available languages is as follows:

{{Article summary heading|Available in languages}}
{{i18n entry|English|Article title}}
....

Even if your article has no translations, it is a good idea to list at least the language your article is written in. That will allow translators to easily add new i18n entries by simply copying the existing one.

Note: The heading for available languages is Available in languages.

For a more complete article overview box, you will usually want to list the required software or hardware. When listing software, it is recommended that you provide a link to the software's home page. That can be done by using Article summary link template.

{{Article summary heading|Required software}}
{{Article summary link|Name of software (version)|http://www.link2software.com/}}
....

Hardware can be listed either by linking to the manufacturer's technical data sheet, or manufacturer's web site, or simply by naming a piece of hardware. You need a minimum of model and make for the list to be of any use. The following example uses the last method:

{{Article summary heading|Required hardware}}
{{Article summary text|Name of hardware (Manufacturer)
....

Finally, it is a nice touch to find and link to related articles on ArchWiki. This is done by using Article summary wiki template:

{{Article summary heading|Related articles}}
{{Article summary wiki|Related article title}}
....

Let us see the complete overview box now:

{{Article summary start}}
{{Article summary text|This is a short summary}}
{{Article summary heading|Available in languages}}
{{i18n entry|English|Article title}}
{{Article summary heading|Required software}}
{{Article summary link|Name of software (version)|http://www.link2software.com/}}
{{Article summary heading|Required hardware}}
{{Article summary text|Name of hardware (Manufacturer)
{{Article summary heading|Related articles}}
{{Article summary wiki|Related article title}}
{{Article summary end}}

Of course, you many add more headings to the overview box. This is a recommendation for a standard list of overview headings:

  • Article summary (required; brief summary of the article)
  • Available in languages (required; links to translations)
  • Series (list all articles in a series of related articles)
  • Legal (possible legal issues)
  • Required software (links to required software)
  • Required hardware (links to, or list of required hardware)
  • Related articles (links to other related wiki articles)