Help:Your first article: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
m (→‎Contributing to the FlightGear Wiki: http://forum.flightgear.org/viewtopic.php?f=72&t=22796)
(→‎Creating a new article: Breaking out an entire section on sandbox pages.)
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Wiki help navbar}}
:''Jump straight to [[#Formatting the wiki text|Formatting the wiki text]] if you are in a hurry''.
Writing '''your first article''' could be a great way to share your experiences and perhaps also help some of us other FlightGear users.  Hopefully your first wiki article will be only one of many contributions to the FlightGear project.
Writing '''your first article''' could be a great way to share your experiences and perhaps also help some of us other FlightGear users.  Hopefully your first wiki article will be only one of many contributions to the FlightGear project.


As you probably already are aware of the FlightGear wiki is a collaborative written documentation related to FlightGear, the free and open source flight simulator.  As FlightGear itself the wiki is licensed under the [[GPL|GNU GPL version 2]] license.
As you probably already are aware of the FlightGear wiki is a collaborative written documentation related to FlightGear, the free and open source flight simulator.  As FlightGear itself the wiki is licensed under the [[GPL|GNU GPL version 2]] license.
== Wiki Markup Basics ==
See: http://forum.flightgear.org/viewtopic.php?f=72&t=22796


== Contributing to the FlightGear Wiki ==
== Contributing to the FlightGear Wiki ==
The FlightGear Wiki is not an encyclopaedia or a search paper.  There is no requirement to have primary and secondary sources, unless you are citing something.  In fact, much of what is needed does not exist anywhere else at all!
The FlightGear Wiki is not an encyclopaedia or a search paper.  There is no requirement to have primary and secondary sources, unless you are citing something.  In fact, much of what is needed does not exist anywhere else at all!


Original research, opinions, and first hand accounts are the majority of the content here, but please do not plagiarize. If you are going to copy or cite something then provide a reference (like you might for a school paper). Other than that, the standards and specific goals of the FlightGear are still in flux and development.
Original research, opinions, and first hand accounts are the majority of the content here, but please do not plagiarize. If you are going to copy or cite something then provide a reference (like you might for a school paper). Other than that, the standards and specific goals of FlightGear are still in flux and being developed.


Articles tend to be about whatever someone sees as important, useful, or fun enough to write about!
Articles tend to be about whatever someone sees as important, useful, or fun enough to write about!


== More about what to write about ==
== More about what to write about ==
The FlightGear Wiki has a few main areas that continuously needs work:
The FlightGear Wiki has a few main areas that continuously need work:


; Development related articles
; Development related articles
Line 20: Line 21:


; Usage related articles
; Usage related articles
: Documentation to get the users started, how to use various features, FAQ:s etc.
: Documentation to get the users started, how to use various features, FAQs, etc.


; Aircraft related articles
; Aircraft related articles
: Documentation about the official aircraft
: Documentation about the official aircraft


If you do not yet feel fully ready to start an new article there are also categories various articles that could need some true loving care like, [[:Category:Stubs|very short articles (stubs)]], [[:Category:Articles considered for deletion|articles considered for deletion]] and [[:Category:Cleanup|articles needing cleanup]].  Helping out with those could be a way to getting to know the wiki and familiarize yourself with the wiki markup.
If you do not yet feel fully ready to start a new article there are also categories of various articles that could need some tender loving care such as:  [[:Category:Stubs|very short articles (stubs)]], [[:Category:Articles considered for deletion|articles considered for deletion]] and [[:Category:Cleanup|articles needing cleanup]].  Helping out with those could be a good way to familiarize yourself with the wiki as well as the wiki markup.


Other interesting pages include things like [[Real Life Experience]], [[Linux software audio mixing with FlightGear]], [[Current events]], or [[Presentation Recipe]]!  
Other interesting pages include things like [[Real Life Experience]], [[Linux software audio mixing with FlightGear]], [[Current events]], or [[Presentation Recipe]]!  


== Creating a new article ==
== Creating a new article ==
Here are some things to think of before starting a new article.
Here are some things to consider before starting a new article.
 
=== Sandbox pages ===
You can create a sandbox page, in essence an article as a subpage to your user page, if you know that you will be working on the article a bit now and then but do not want to leave an unfinished article in the article namespace.
 
You can create a subpage to your user page by giving it the name '''User:''User name''/''Article name'''''.  To make it easier to find you can make a link to it on your user page.  When you are more or less done, you can then move this page to the article space.


=== Choosing a good title ===
=== Choosing a good title ===
Consider giving the template a meaningful name. Usually one would try to only have the initial character upper case.  Do not use abbreviations for an article title.  You your article title should instead be spelled out and a redirect page for the abbreviation to your article should be created.
Give the page a meaningful name. Usually one would try to only have the initial character upper case.  Do not use abbreviations for an article title.  Your article title should be spelled out. If an abbreviation is commonly used, you may create a separate page consisting of the abbreviated title and a page redirect, which will refer the reader back to your main article.


You can also create an article as a subpage to your user page if you know that you will be working on the article a bit now and then, but do not want to leave unfinished article in the article namespace.  You can create a subpage to your user page by giving it the name '''User:''User name''/''Article name'''''.  To make it easier to find you can make a link to it on your user page.  When you are more or less done, you can then move this page to the article space.
=== Search and create ===
In essence: Search first, then create.


=== Search first, then create ===
To create a new article, please start by using the search function. This way you will find if there already is an article with that name or if there is one with a very similar name. If there is no article with that name you will be presented with the option to create that page. Click on the blue link prompting you to create new page to go to an edit page.
To create a new article, please start by using the search function. This way you will find if there already is an article with that name or if there is one with a very similar name. If there is no article with that name you will be presented with the option to create that page. Click on the red link to open up an edit window.


=== Preview early, and preview often ===
=== Preview early, and preview often ===
This is important.  First of all, and specially if you are new to editing a wiki, you will get a better feeling for what your article will look like.  Sometimes you will find that some sections are way longer than you thought, or that an image needs to be larger to be intelligible.  Some of the wiki markup is more fragile than other, in particular [[Help:Tables|tables]], and it is much easier to fix such markup early on knowing where in the markup things broke than later.  In addition to that reading your own text will often help you find a better phrasing.
This is important.  First of all, and especially if you are new to editing a wiki, you will get a better feeling for what your article will look like.  Sometimes you will find that some sections are way longer than you thought, or that an image needs to be larger to be intelligible.  Some of the wiki markup is more fragile than other, in particular [[Help:Tables|tables]], and it is much easier to fix such markup early on knowing where in the markup things broke than later.  In addition to that reading your own text will often help you find a better phrasing.


Before saving the article, do have an extra preview, and a more thorough read through.
Before saving the article, do have an extra preview, and a more thorough read through.
Line 53: Line 59:


== Typical article disposition ==
== Typical article disposition ==
Consider this a recommendation.  Though most of the articles follow this convention some don't.
{{main article|FlightGear wiki:Style guide – Article disposition}}


=== Generic disposition ===
Consider this as a recommendation.  Though most of the articles follow this convention, some don't.
  <nowiki>{{Some messagebox}}
  <nowiki>{{Some messagebox}}
{{Some other messagebox}}
{{Some other messagebox}}
Line 63: Line 71:
[[File:Some other image.jpg|thumb|Some other caption]]
[[File:Some other image.jpg|thumb|Some other caption]]


A '''generic article disposition''' would look something like this.
The first section of a '''generic article disposition''' would look something like this.


== Heading ==
== Heading ==
Line 72: Line 80:


== Related content ==
== Related content ==
* [[Some page]]
* [[Some wiki link]] – Some description


== External links ==
== External links ==
* [Some link] Some description
* [Some external link] Some description


{{Some navbox}}
{{Some navbox}}
Line 81: Line 89:
[[en:Some language link]]
[[en:Some language link]]


[[Category:Some category]]</nowiki>
[[Category:Some category link]]</nowiki>
 
=== The first section ===
One important thing to put some attention on is the first sectionof the article. It should be a ''short summary'' of the article.  Preferably the '''page title in bold''' should be within the first sentence of the first section.  This short summary should help a reader to quickly figure out if he found the page he was looking for, as well as help him grasp the main concepts of the article.
 
== Formatting the wiki text ==
{{main article|Help:Formatting}}
 
If you have just used Open Office, then it is still easy to get started, as you can begin using the buttons above the edit box to format your text.  The wiki markup is rather easy to remember though.  A few simple examples are shown below:


;Messageboxes
{| class="wikitable" width="100%"
:One or more ''messageboxes'' could sometimes begin typical article page.  The messageboxes would tell a reader or editor something about the article, like for example that it is outdated due to new developments.
! Description
! width="30%" | What you type
! width="30%" | What you get
|-
| Italic and bold text.
|
<nowiki>''Italic'' and '''bold''' text.</nowiki>
| ''Italic'' and '''bold''' text.
|-
| Headings
|
<nowiki>== Level 2 ==</nowiki>
<nowiki>=== Level 3 ===</nowiki>
  <nowiki>==== Level 4 ====</nowiki>
|
== Level 2 ==
=== Level 3 ===
==== Level 4 ====
|-
| Links to wiki pages. The first character is case insensitive.
|
<pre style="white-space: pre-wrap;">Here is a [[list of abbreviations]].


;Infobox or navbox
A [[Help:Templates|template]] can be very practical.</pre>
:Often an ''infobox'' or ''navbox'' will follow. An ''infobox'' will contain more detailed information about a piece of software, an aircraft, an airport etc. that is the topic of the article and a ''navbox'' could help the reader find his way around a series of or similar articles.
| Here is a [[list of abbreviations]].


;Images
A [[Help:Templates|template]] can be very practical.
:Many articles would be helped by additional imagesWhile it is often a good idea to have at least one of them on top of the article, as this will help a reader to figure out if he landed on the right article and what it is about.   While they can all be in the beginning of the article text, they can just as well be spread out within the articleMost of the time having just thumbnail images will be preferable.
|-
| Unordered lists
|
<nowiki>* Item
* Item</nowiki>
|
* Item
* Item
|-
| Ordered lists
|
<nowiki># Item
# Item</nowiki>
|
# Item
# Item
|-
| Definition lists
|
  <nowiki>; Term
: Definition</nowiki>
|
; Term
: Definition
|-
| Indentation is usually the way comments from different users are separated on discussion pages.
|
<nowiki>No indentation
:Indentation
::Indentation</nowiki>
|
No indentation
:Indentation
::Indentation
|-
| Tables
|
<nowiki>{| class="wikitable"
! Cell one !! Cell two
|-
| Cell three || Cell four
|}</nowiki>
|
{| class="wikitable"
! Cell one !! Cell two
|-
| Cell three || Cell four
|}
|-
| Nasal and XML highlighting. See also [[Help:Formatting#Syntax highlighting]].
|
  <pre style="white-space: pre-wrap;"><syntaxhighlight lang="nasal" enclose="div">
# Snippet
</syntaxhighlight>


;First section
<syntaxhighlight lang="xml" enclose="div">
:The ''first section'' of an article should be a ''short summary'' of the article or an ingress. Preferably the '''page title in bold''' should be within the first sentence or the first section.
  <!-- Snippet -->
:This short summary of the article would help a reader to quickly figure out if he found the page he was looking for, as well as help a him grasp the main concepts of an article a bit faster.
</syntaxhighlight></pre>
| <syntaxhighlight lang="nasal" enclose="div">
# Snippet
</syntaxhighlight>


;Article text
<syntaxhighlight lang="xml" enclose="div">
:The article text that follows is preferably broken up in not too long, but not too short ''sections'' separated by headings and subheadings.  Often it would help the reader if there are images and tables to help understand the article text. Sometimes it is a good thing to mark more some important words differently.
<!-- Snippet -->
</syntaxhighlight>
|-
| Images and thumbnail images
|
  <nowiki>[[File:Canvasready.png|100px]]


;Links to related content
[[File:Fg wings large.png|thumb|150px|Logo]]</nowiki>
:''Links'' to related content, like other articles forum topics etc. can be put in the end, though in general having the internal wikilinks within the article text is preferable.
|
[[File:Canvasready.png|100px]]


;Links to external resources
[[File:Fg wings large.png|thumb|150px|Logo]]
:Links to external resources should be put at the very end of the article.
|-
| Progress templates
|
<nowiki>{{done}}


;Navbox
{{pending}}
:Many pages end with a ''navbox'' with for example other aircraft by the same manufacturer.


;Language links and categories
{{not done}}
:All articles should end with one or more ''categories''. They are preceded by ''language links'', if there is any translations of that page.


== Formatting the wiki text ==
{{progressbar|50}}
{{main article|Help:Formatting}}
</nowiki>
|
{{done}}


If you have just used Open Office, then it is still easy to get started, as you can begin using the buttons above the edit box to format your text.  The wiki markup is rather easy to remember though.  A few examples of what can be done is shown below:
{{pending}}


<nowiki>* The most common markup is very easy, here also demonstrating unordered and ordered lists:
{{not done}}
*# ''Italic text'' is done within two apostrophes
*# '''Bold text''' is done within three apostrophes
*# '''''Bold italic text''''' is done with five apostrophes
*#* Thus '''Bold and ''bold italic''''' text can be mixed
: Indented text is done with one or more colon at the beginning of each indented paragraph</nowiki>


* The most common markup is very easy, here also demonstrating unordered and ordered lists:
{{progressbar|50}}
*# ''Italic text'' is done within two apostrophes
|-
*# '''Bold text''' is done within three apostrophes
| Embedded YouTube videos, here https://www.youtube.com/watch?v=yWEyRVGJks0
*# '''''Bold italic text''''' is done with five apostrophes
|
*#* Thus '''Bold and ''bold italic''''' text can be mixed
<nowiki>{{#ev:youtube|yWEyRVGJks0}}</nowiki>
: Indented text is done with one or more colon at the beginning of each indented paragraph
| ''This example not shown''
|}


== Linking your article to other articles ==
== Linking your article to other articles ==
Line 154: Line 252:


=== Navboxes ===
=== Navboxes ===
Navboxes, or navigation templates, are boxes helping navigating a series of related articles.  They come in two flavours, one kind that is found to the top right of the article, often linking together a series of articles on a certain topic, and a kind that is found at the bottom of the article linking together related articles, for example aircraft by the same manufacturer or different articles related to building FlightGear from source files.
Navboxes, or navigation templates, are boxes helping navigating a series of related articles.  They come in two varieties, one kind that is found to the top right of the article, often linking together a series of articles on a certain topic, and a kind that is found at the bottom of the article linking together related articles, for example aircraft by the same manufacturer or different articles related to building FlightGear from source files.


[[Category:Help]]
[[Category:Help]]

Revision as of 07:46, 4 August 2018


Jump straight to Formatting the wiki text if you are in a hurry.

Writing your first article could be a great way to share your experiences and perhaps also help some of us other FlightGear users. Hopefully your first wiki article will be only one of many contributions to the FlightGear project.

As you probably already are aware of the FlightGear wiki is a collaborative written documentation related to FlightGear, the free and open source flight simulator. As FlightGear itself the wiki is licensed under the GNU GPL version 2 license.

Contributing to the FlightGear Wiki

The FlightGear Wiki is not an encyclopaedia or a search paper. There is no requirement to have primary and secondary sources, unless you are citing something. In fact, much of what is needed does not exist anywhere else at all!

Original research, opinions, and first hand accounts are the majority of the content here, but please do not plagiarize. If you are going to copy or cite something then provide a reference (like you might for a school paper). Other than that, the standards and specific goals of FlightGear are still in flux and being developed.

Articles tend to be about whatever someone sees as important, useful, or fun enough to write about!

More about what to write about

The FlightGear Wiki has a few main areas that continuously need work:

Development related articles
Documentation for FlightGear core, scenery and aircraft developers
Usage related articles
Documentation to get the users started, how to use various features, FAQs, etc.
Aircraft related articles
Documentation about the official aircraft

If you do not yet feel fully ready to start a new article there are also categories of various articles that could need some tender loving care such as: very short articles (stubs), articles considered for deletion and articles needing cleanup. Helping out with those could be a good way to familiarize yourself with the wiki as well as the wiki markup.

Other interesting pages include things like Real Life Experience, Linux software audio mixing with FlightGear, Current events, or Presentation Recipe!

Creating a new article

Here are some things to consider before starting a new article.

Sandbox pages

You can create a sandbox page, in essence an article as a subpage to your user page, if you know that you will be working on the article a bit now and then but do not want to leave an unfinished article in the article namespace.

You can create a subpage to your user page by giving it the name User:User name/Article name. To make it easier to find you can make a link to it on your user page. When you are more or less done, you can then move this page to the article space.

Choosing a good title

Give the page a meaningful name. Usually one would try to only have the initial character upper case. Do not use abbreviations for an article title. Your article title should be spelled out. If an abbreviation is commonly used, you may create a separate page consisting of the abbreviated title and a page redirect, which will refer the reader back to your main article.

Search and create

In essence: Search first, then create.

To create a new article, please start by using the search function. This way you will find if there already is an article with that name or if there is one with a very similar name. If there is no article with that name you will be presented with the option to create that page. Click on the blue link prompting you to create new page to go to an edit page.

Preview early, and preview often

This is important. First of all, and especially if you are new to editing a wiki, you will get a better feeling for what your article will look like. Sometimes you will find that some sections are way longer than you thought, or that an image needs to be larger to be intelligible. Some of the wiki markup is more fragile than other, in particular tables, and it is much easier to fix such markup early on knowing where in the markup things broke than later. In addition to that reading your own text will often help you find a better phrasing.

Before saving the article, do have an extra preview, and a more thorough read through.

Creating redirect pages

Creating a redirect page, an empty page whose only purpose is to redirect to your article, is recommended if your article title is also known as an abbreviation (for example an ICAO airport code), another less common name or is often misspelled.

Creating a redirect page is very easy. The same way you search and then create the article, you search and then create the redirect page. The only contents of the redirect page should be like below:

#REDIRECT [[Article name]]

Typical article disposition

1rightarrow.png See FlightGear wiki:Style guide – Article disposition for the main article about this subject.

Generic disposition

Consider this as a recommendation. Though most of the articles follow this convention, some don't.

{{Some messagebox}}
{{Some other messagebox}}

{{Some infobox or navbox}}

[[File:Some image.jpg|thumb|Some caption.]]
[[File:Some other image.jpg|thumb|Some other caption]]

The first section of a '''generic article disposition''' would look something like this.

== Heading ==
Some text...

=== Subheading ===
Some text...

== Related content ==
* [[Some wiki link]] – Some description

== External links ==
* [Some external link] – Some description

{{Some navbox}}

[[en:Some language link]]

[[Category:Some category link]]

The first section

One important thing to put some attention on is the first sectionof the article. It should be a short summary of the article. Preferably the page title in bold should be within the first sentence of the first section. This short summary should help a reader to quickly figure out if he found the page he was looking for, as well as help him grasp the main concepts of the article.

Formatting the wiki text

1rightarrow.png See Help:Formatting for the main article about this subject.

If you have just used Open Office, then it is still easy to get started, as you can begin using the buttons above the edit box to format your text. The wiki markup is rather easy to remember though. A few simple examples are shown below:

Description What you type What you get
Italic and bold text.
''Italic'' and '''bold''' text.
Italic and bold text.
Headings
== Level 2 ==
=== Level 3 ===
==== Level 4 ====

Level 2

Level 3

Level 4

Links to wiki pages. The first character is case insensitive.
Here is a [[list of abbreviations]].

A [[Help:Templates|template]] can be very practical.
Here is a list of abbreviations.

A template can be very practical.

Unordered lists
* Item
* Item
  • Item
  • Item
Ordered lists
# Item
# Item
  1. Item
  2. Item
Definition lists
; Term
: Definition
Term
Definition
Indentation is usually the way comments from different users are separated on discussion pages.
No indentation
:Indentation
::Indentation

No indentation

Indentation
Indentation
Tables
{| class="wikitable"
! Cell one !! Cell two
|-
| Cell three || Cell four
|}
Cell one Cell two
Cell three Cell four
Nasal and XML highlighting. See also Help:Formatting#Syntax highlighting.
<syntaxhighlight lang="nasal" enclose="div">
# Snippet
</syntaxhighlight>

<syntaxhighlight lang="xml" enclose="div">
 <!-- Snippet -->
</syntaxhighlight>
# Snippet
 <!-- Snippet -->
Images and thumbnail images
[[File:Canvasready.png|100px]]

[[File:Fg wings large.png|thumb|150px|Logo]]

Canvasready.png

Logo
Progress templates
{{done}}

{{pending}}

{{not done}}

{{progressbar|50}}

Done Done

Pending Pending

Not done Not done

50}% completed

Embedded YouTube videos, here https://www.youtube.com/watch?v=yWEyRVGJks0
{{#ev:youtube|yWEyRVGJks0}}
This example not shown

Linking your article to other articles

Linking your article to other articles will make your article more useful to the reader, as well as make it easier to find using search engines. There is mainly three ways to do this:

  1. By adding wiki links
  2. By adding one or more category
  3. By adding a navbox.

Wikilinks

1rightarrow.png See Help:Formatting#Links to other wiki pages for the main article about this subject.

Wikilinks are links to other articles. You should preferably not link to other articles in the first section or in section headings and you should only link to other articles the first time a concept is used unless the article is very long. Filling the article with links will not make it easier to read it.

Wikilinks can be used in a few different ways.

Here is some example links:  [[Aircraft speed]], [[altitude]]s and [[Modeling - Getting Started#Finding, Creating, or Using Textures|textures]].

Here is some example links: Aircraft speed, altitudes and textures.

Categories

1rightarrow.png See Help:Categories for the main article about this subject.

The categories is connecting the articles, images, and templates in a partly tree-like partly web-like structure. By linking together similar content it will be easier to get a grasp on how your article is related to other articles.

Have a look in the category structure and try find a suitable category or maybe one or two more. Adding a category that is as narrow as possible to your article will help find it for a reader browsing through the categories looking for something.

Categories are added like this [[Category:Some category]] at the very bottom of the page. Sometimes it is desirable to add a category in a way that the article will be sorted differently than by it's name. This can be done like this [[Category:Some category|Sort key]], where the sort key is what it should be sorted as instead of the article name.

Navboxes

Navboxes, or navigation templates, are boxes helping navigating a series of related articles. They come in two varieties, one kind that is found to the top right of the article, often linking together a series of articles on a certain topic, and a kind that is found at the bottom of the article linking together related articles, for example aircraft by the same manufacturer or different articles related to building FlightGear from source files.