Difference between revisions of "Writing Article Overviews"

From ArchWiki
Jump to: navigation, search
(fix double redirect)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Help]]
+
#REDIRECT [[Help:Writing article introductions]]
{{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 heading|Series}}
+
{{Article summary wiki|Writing Short Article Names}}
+
{{Article summary wiki|Writing Article Overviews}}
+
{{Article summary wiki|Writing Article Introductions}}
+
{{Article summary wiki|Effective Use of Headers}}
+
{{Article summary heading|Related}}
+
{{Article summary wiki|Help:Editing}}
+
{{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 [[Help:Editing|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 required software, required hardware, related articles, etc.
+
 
+
== The text ==
+
 
+
An effective article is one that fulfills its intended purpose. In order to fulfill 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:
+
 
+
#What will I be able to achieve after I read this article?
+
#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 inside a box on the right.''
+
*Answer to second question: ''This article covers some style questions, writing tips, and formatting techniques.''
+
 
+
As you can see, you do not 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 overview, 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:
+
 
+
* [[Template:Article summary start|Article summary start]]
+
* [[Template:Article summary end|Article summary end]]
+
* [[Template:Article summary text|Article summary text]]
+
* [[Template:Article summary heading|Article summary heading]]
+
* [[Template:Article summary link|Article summary link]]
+
* [[Template:Article summary wiki|Article summary wiki]]
+
 
+
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:
+
 
+
<pre>
+
{{Article summary start}}
+
{{Article summary text|This is a short summary}}
+
{{Article summary end}}
+
</pre>
+
 
+
Try it out in the [[Sandbox]]. Just copy the code above and paste it there. Preview or save the page to see the results.
+
 
+
At the very least, an article overview box should contain the ''article summary''.
+
 
+
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.
+
 
+
<pre>
+
{{Article summary heading|Required software}}
+
{{Article summary link|Name of software (version)|http://www.link2software.com/}}
+
....
+
</pre>
+
 
+
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:
+
 
+
<pre>
+
{{Article summary heading|Required hardware}}
+
{{Article summary text|Name of hardware (Manufacturer)
+
....
+
</pre>
+
 
+
Finally, it is a nice touch to find and link to related articles on ArchWiki. This is done by using ''Article summary wiki'' template:
+
 
+
<pre>{{Article summary heading|Related}}
+
<nowiki>{{Article summary wiki|Related article title}}
+
....
+
</pre>
+
 
+
Let us see the complete overview box now:
+
 
+
<pre>
+
{{Article summary start}}
+
{{Article summary text|This is a short summary}}
+
{{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}}
+
{{Article summary wiki|Related article title}}
+
{{Article summary end}}
+
</pre>
+
 
+
Of course, you may 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)
+
* 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 (links to other related wiki articles)
+

Latest revision as of 04:04, 1 March 2014