Difference between revisions of "Help:Editing"

Revision as of 08:43, 2 December 2015

[edit]

Introduction

For the basics about MediaWiki please read MediaWiki FAQ
In the beginning, the Cheatsheat is very useful

Most frequently asked

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 here
Templates are used if appropriate, find a 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
Metaclasses: METACLASSSCOPE, QUERYSCOPE
Classifications: SYSCLS TASK, SYSCLS THUMBNAILEDFILE (with properties)
How-To: Create a new MetaClass

It is common to use the expression: Save the changes with Ctrl+S or the save command

Do also use screenshots in How-To‘s, so that the reader is guided visually.

Texts

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

→ Task a

→ 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 <syntaxhighlight> tags within the numbered items, use one of the following workarounds to preserve continuous numbering:

# Item 1
# Item 2 <!--
--><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
# Item 3
# Item 4 <br /><syntaxhighlight lang="xml">
<Node1>Value1</Node1>
</syntaxhighlight>
# Item 5

Using a HTML comment  OR <br/> for the line break prevents that the numbered list is broken and numbering starts over:

Item 1
Item 2
<Node1>Value1</Node1>
Item 3
Item 4
<Node1>Value1</Node1>
Item 5

Obeying this syntax it is also possible to use the {{Hints}} and {{Attention}} templates:

# Item 1
# Item 2 <!--
-->{{Hint|asdfasdf}}
# Item 3
# Item 4 <!--
-->{{Attention|asdfasdf}}
# Item 5

Item 1
Item 2
asdfasdf
Item 3
Item 4
asdfasdf
Item 5

Tables

Use the WikiTable like in the following example:

{| 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

|- |}

will result in

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:

{| 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

|- |}

will result in

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>-Tag 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, ...).

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

which will result in

// Hello World in Microsoft C#.

using System;

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

Images

Wiki specific templates

Check the 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:

Prefix	Description	Examples
UI_	screenshots of UBIK^® Studio, UBIK^® Client, Windows (IIS, SQL, Excel, ...)	UBIK UI
IL_	Illustrations (diagrams, fractions of slides, ...)	-
SY_	UBIK^® symbols (e.g. images for MetaClass, BASECLASS, relations, ...)	-
IC_	small graphics (icons, arrows, ...)	UBIK Icons

Formats

Supporting images

Example Supporting images

Supporting images must be formatted as thumb 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

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: [[File:Example.jpg|700px|border|alt=Example|Example]]

Borders

Use the border parameter in the tag for the embedded image, for example [[File:Example.jpg|border]] results in

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

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

which results in

1 - Example
2 - Example
3 - Example

{{Clear}} Template

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

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

Section 1 starts here

Example

Some text 1

Watch that section 2 starts after some spacing.

Section 2 starts here

Example

Some text 2

@@ Line 7: / Line 7: @@
 == Most frequently asked ==
 * [[Help:List_of_Templates|Available templates]]
-* [[Help:List_of_Templates|Available templates]]
+* [[Help:Editing#Lists|Editing lists]]
+* [[Help:Editing#tab=Categorizing|Categories]]
 == Acceptance criteria ==

Main category	Namespace	Example
How-To	HowTo	HowTo:Assign_a_Namespace
FAQ	FAQ	FAQ:UBIK_Studio
Activity	Activity	Activity:DebugMessage

Category	Preload template	Example
How-To	Template:HowTo/Preload	HowTo/Preload
Activity	Template:Activity/Preload	Activity/Preload