View source for Help:Editing

=Introduction=

== Introduction ==

*For the basics about MediaWiki please read ''[http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]''

*In the beginning, the [http://en.wikipedia.org/wiki/Wikipedia:Cheatsheet Cheatsheat] is very useful

== Acceptance criteria ==
Any article should meet the following general acceptance criteria
* Is the article structured logically and coherently?
* Can the reader be directed to any other article (eg See also...)? 
* Is the article categorized into at least one category?
* If the article links to other articles, check whether or not they exist?
* Check the article for integrity and correctness in regards of technical descriptions. Test the described procedure and verify possible dependencies on versions.
* Check the article for linguistic correctness in regards to grammar and style.
* Images are prepared as described [[Help:Editing#Images|here]]
* Templates are used if appropriate, find a list of templates [[Help:List_of_Templates|here]]
* Meet all (additional) requirements defined in this guideline

=Formatting=
== Reference articles ==
Please have a look at the following reference articles
* [[Entity_Data_Model]], [[Class Browser]]
* [[:Category:Metaclasses]]: [[METACLASSSCOPE]], [[QUERYSCOPE]]
* [[:Category:Classifications]]: [[SYSCLS_TASK]], [[SYSCLS_THUMBNAILEDFILE]] (with properties)
* How-To: [[HowTo:Create a new MetaClass]]

{{Hint|It is common to use the expression: ''Save the changes with {{key press|Ctrl|S}} or the save command''}}
{{Hint|Do also use screenshots in How-To‘s, so that the reader is guided visually.}}

==Descriptive text==
Descriptive text should be left aligned and in the standard font, without any additional formatting. 

==Emphasizing==
If you want to emphasize something, use '''bold''' style.

==Colors==
Colors should be used very sparingly and only if they really contribute to the better understanding of a text.

==UI==
If you want to refer to the exact name of something in the UI of {{UBIK}}, use ''italic'' style.

==Headlines==
Use the general headline formatting, type in regular case.

==Infoboxes==
Infoboxes should be used as an introduction for articles that have a useful common denominator. They will appear at the top right ans summarize the article in Keywords and/or pictures. Currently there is a template for a [[Template:ControlInfoBox|Control Infobox]] implemented that should be used for all articles about {{UBIK}} controls.

==Lists==
There are two types of lists that can be used:

===Bullets===
Use a bullets if you want to list several (short) statements of the same area, which are not chronologically connected. Do not use punctuation for bulleted items.
* Statement
* Another Statement

In addition, if you want to list certain tasks that do not follow a particular order you can use right arrows:

&rarr; Task a

&rarr; Task b

===Numbered list===
Use numbered list if the items are chronologically connected and have to be executed one after the other. Do not use punctuation for bulleted items.
# Do this first
# then do this
# end finally, do this

If you want to add special formatted content, like ''<nowiki><syntaxhighlight></nowiki>'' tags within the numbered items, use one of the following workarounds to preserve continuous numbering:
<pre>
# Item 1
# Item 2 <!--
--><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
# Item 3
# Item 4 <br /><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
</pre>
# Item 5

Using a HTML comment <nowiki><!-- --></nowiki> '''OR''' <nowiki><br/></nowiki> for the line break prevents that the numbered list is broken and numbering starts over:
# Item 1
# Item 2 <!--
--><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
# Item 3
# Item 4 <br /><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
</pre>
# Item 5

Obeying this syntax it is also possible to use the <nowiki>{{Hints}}</nowiki> and <nowiki>{{Attention}}</nowiki> templates:
# Item 1
# Item 2 <!--
-->{{Hint|asdfasdf}}
# Item 3
# Item 4 <!--
-->{{Attention|asdfasdf}}
# Item 5

==Tables==

Use the WikiTable like in the following example:

<code>{| class="wikitable sortable" | width = "50%"

|-
! Columns 1!! Column 2

|-
| Row 1.1|| Row 1.2

|-
| Row 2.1|| Row 2.2

|-
| Row 3.1|| Row 3.2

|-
|}</code>

will result in

{| class="wikitable sortable" | width = "50%"
|-
! Columns 1!! Column 2
|-
| Row 1.1|| Row 1.2
|-
| Row 2.1|| Row 2.2
|-
| Row 3.1|| Row 3.2
|-
|}

For larger data, the sortable table might be more useful:

<code>{| class="wikitable sortable" | width = "50%"

|-
! Columns 1!! Column 2

|-
| Row 1.1|| Row 1.2

|-
| Row 2.1|| Row 2.2

|-
| Row 3.1|| Row 3.2

|-
|}</code>

will result in

{| class="wikitable sortable" | width = "50%"
|-
! Columns 1!! Column 2
|-
| Row 1.1|| Row 1.2
|-
| Row 2.1|| Row 2.2
|-
| Row 3.1|| Row 3.2
|-
|}

==Code==
 Use either a leading blank to format text as source code, or the <code><code>-Tag</code> for regular code highlighting.

For highlighting a syntax of a specific programming language, use the syntaxhighlight-Tag (values for '''lang''' are for example: csharp, xml, ...).

<pre><nowiki>
<syntaxhighlight lang="csharp">
// Hello World in Microsoft C#.

using System;

class HelloWorld
{
    public static int Main(String[] args)
    {
        Console.WriteLine("Hello, World!");
        return 0;
    }
}
</syntaxhighlight>
</nowiki></pre>

which will result in

<syntaxhighlight lang="csharp">
// Hello World in Microsoft C#.

using System;

class HelloWorld
{
    public static int Main(String[] args)
    {
        Console.WriteLine("Hello, World!");
        return 0;
    }
}
</syntaxhighlight>

=Images=
==Wiki specific templates==
Check the [[Help:List of Images|list of images]] for this Wiki.

==Naming conventions==
To obtain some kind of categorization the name of new images must start with one a prefix. Choose the most appropriate one from the below list:
{| class="wikitable sortable" | width = "50%"
|-
! Prefix !! Description !! Examples
|-
| UI_|| screenshots of {{UBIK}} Studio, {{UBIK}} Client,  Windows (IIS, SQL, Excel, ...) || [[Help:List_of_Images|UBIK UI]]
|-
| IL_|| Illustrations (diagrams, fractions of slides, ...) || -
|-
| SY_|| {{UBIK}} symbols (e.g. images for MetaClass, BASECLASS, relations, ...) || -
|-
| IC_|| small graphics (icons, arrows, ...) || [[Help:List_of_Images#Icons|UBIK Icons]]
|-
|}

==Formats==

=== Supporting images ===
[[File:Example.jpg|220px|thumb|border|alt=Example Supporting images|Example Supporting images]]
Supporting images must be formatted as <code>thumb</code> to make them appear on the right side, with the following dimensions:
* Images in portrait format with 170 pixels width
* Images in landscape format with 220 pixels width

Example: <code><nowiki>[[File:Example.jpg|220px|thumb|border|alt=Example|Example]]</nowiki></code>
{{Clear}}

=== Descriptive images ===
Images as part of the descriptive article text can be placed inline, like for emphasizing a certain manual visually, with the following dimensions:
* Images in landscape should not exceed 700 pixels width
* Images in portrait should not exceed 700 pixels height

Example: <code><nowiki>[[File:Example.jpg|700px|border|alt=Example|Example]]</nowiki></code>

=== Borders ===
Use the '''border''' parameter in the tag for the embedded image, for example <code><nowiki>[[File:Example.jpg|border]]</nowiki></code> results in<br/>[[File:Example.jpg|border]]

=== Image captions ===
Use image captions if appropriate to describe the image and to create a relation to the text.

== Gallery style ==
If there is the need to place a series of images within the text use the gallery tag with an appropriate width and height

<code><nowiki><gallery widths="200" heights="200"></nowiki></code><br/>
<code><nowiki>File:Example.jpg|1 - Example</nowiki></code><br/>
<code><nowiki>File:Example.jpg|2 - Example</nowiki></code><br/>
<code><nowiki>File:Example.jpg|3 - Example</nowiki></code><br/>
<code><nowiki></gallery></nowiki></code>

which results in

<gallery widths="200" heights="200">
File:Example.jpg|1 - Example
File:Example.jpg|2 - Example
File:Example.jpg|3 - Example
</gallery>

== <nowiki>{{Clear}}</nowiki> Template ==
If one or more images should be located next to the descriptive text but which is organized in several sections, use the <nowiki>{{Clear}}</nowiki> template. Have a look at the below section example:

{{Attention|Use this command very rarely - try to place the images in a gallery style!}}

=== Section 1 starts here ===
[[File:Example.jpg|220px|thumb|border|alt=Example|Example]]
Some text 1

Watch that section 2 starts after some spacing.
{{Clear}}

=== Section 2 starts here ===
[[File:Example.jpg|220px|thumb|border|alt=Example|Example]]
Some text 2
{{Clear}}

=Categorizing=
Each article must be assigned to '''at least one category''' and a maximum of 3 categories. 
* If you feel an article fits into more than 3 categories, consider splitting it into multiple articles
* If you feel an article fits into no category, consider merging it into another article OR use at least the category UBIK
* Do not create new categories every time - check if an existing fits to your needs.

== Sub Categories ==
A new sub category can be created by pasting a category within the source of another category page.

== Sort Key ==
Use sort keys for articles and subcategories, e.g. objects of category [[:Category:Classifications]], so that the article is sorted by a propery sort key instead of S always.
Example: <code><nowiki>[[Category:System Classifications|T]]</nowiki></code>

== Category Tree ==
The articles and categories are evaluated by the [http://www.mediawiki.org/wiki/Extension:CategoryTree Category Tree extension] and used on the [[SiteMap]] page.
* [http://www.mediawiki.org/wiki/Extension:CategoryTree Extension:Category Tree]
* [http://ddowiki.com/page/Help:Extension:CategoryTree Help:Extension:CategoryTree]

=Namespaces=
Certain types of articles should be assigned to a namespace, which is simply done by adding a namespace-prefix in front of the article name like ''<nowiki>HowTo:Assign_a_Namespace</nowiki>''

Find a list of namespaces and how its realted to a main category below.

{| class="wikitable sortable"
|-
! Main category !! Namespace !! Example
|-
| How-To || HowTo || HowTo:Assign_a_Namespace
|-
| FAQ || FAQ || FAQ:UBIK_Studio
|-
| Activity || Activity || Activity:DebugMessage
|}

=Linking=
Internal linking is a good thing, but it must not be used too extensively. Link to the articles that make sense in context of the manual, especially when they are about fundamental principles of {{UBIK}}, like for example the [[MetaClass]] article. Link to each keyword only once in an article, at first appearance of the keyword.

External links only make sense if the target article supports in comprehending an article, for example a certain standard or norm that is used by or in {{UBIK}}, i.e. [http://en.wikipedia.org/wiki/ISO_15926 ISO15926].

=== Download links ===
Use the <nowiki>{{FileLink|1|2}}</nowiki> template to create download links within wiki articles, like {{FileLink|Start_Screen_Configuration.zip|Start_Screen_Configuration.zip}}

=Special articles=
== HowTos ==
Create a [[:Category:How-To|How-To]] to describe '''HOW''' to solve a certain issue. The given instructions should be clear and easy to follow, therefore use screenshots (server and client side) to document your explanations. Use a descriptive name for the How-To article, such that already describes the content.
{{Hint|Consider the KISS principle - '''K'''eep '''I'''t '''S'''hort and '''S'''imple}}
{{Hint|Place images within the items of the numbered list (its width should remain 220 pixels width in landscape or 170 pixels height in portrait orientation).}}

== FAQ ==
Create or edit a [[:Category:FAQ]] page to provide answers to questions or issues the reader would ask using '''WHY''', '''WHO''', '''WHEN''', etc. Provide a short answer, which probably also includes a few instructions.

If the issue requires more detailed explanations refer to an existing wiki article or create a new one.

=Templates=

==Wiki specific templates==
{{Hint|Check the [[Help:List_of_Templates|list of templates]] for a comprehensive list of available templates in this Wiki.}}

== Download links ==
Use the <nowiki>{{FileLink|1|2}}</nowiki> template to create download links within wiki articles.

==Attention==
Use the [[Template:Attention|Attention]] template to draw attention to a certain sentence:
<pre><nowiki>{{Attention|Please don't miss this sentence!}}</nowiki></pre>

will result in 

{{Attention|Please don't miss this sentence!}}

==Hints==
Use the [[Template:Hint|Hint]] template to outline useful tips and hints:
<pre><nowiki>{{Hint|You should read this, it will simplify your work!}}</nowiki></pre>

will result in

{{Hint|You should read this, it will simplify your work!}}

=== HintEvents ===
Use [[Template:HintEvents|HintEvents]] to outline that the type has specific events.
<pre><nowiki>{{HintEvents}}</nowiki></pre>

will result in

{{HintEvents}}

=== HintMethods ===
Use [[Template:HintMethods|HintMethods]] to outline that the type has specific events.
<pre><nowiki>{{HintMethods}}</nowiki></pre>

will result in

{{HintMethods}}

== Infoboxes ==
See also the list of available [[Help:List_of_Templates#Infoboxes|Infoboxes templates]].



==Other useful templates==

* The [[Template:key press|KeyPress]] template allows you to display keyboard commands, so <code><nowiki>{{key press|Ctrl|W}}</nowiki></code> will result in {{key press|Ctrl|W}}
* Use the [[Template:UMM|UBIK MetaModel]] template to refer to the data model:
{{UMM|A descriptive model, where objects provide information about the aspects of the data, is also called “Metamodel”.}}

== Template list ==
A list of available templates can be found here [[Help:List_of_Templates]]

= Wizards =
The '''[[Help:Editing_Wizard|Editing Wizard]]''' offers a convenient way to create articles having a pre-defined structure and purpose.

{| class="wikitable sortable"
|-
! Category !! Preload template !! Example
|-
| How-To || Template:HowTo/Preload || [[Template:HowTo/Preload]]
|-
| Activity || Template:Activity/Preload || [[Template:Activity/Preload]]
|}

<headertabs />

[[Category:Help]]