Editing t20150211
General information
- For the basics about MediaWiki please read MediaWiki FAQ
- In the beginning, the Cheatsheat is very useful
Structuring an article
Basic structuring
For the general structuring of an article, please refer to the following reference articles:
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.
Categories
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
- Do not create new categories every time - check if an existing fits to your needs.
Special articles
HowTos
Create a 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.
 | Consider the KISS principle - Keep It Short and Simple |
FAQ entry
Create a FAQ entry 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.
Text formatting
Descriptive text
Descriptive text should be left aligned and in the standard font, without any additional formatting.
If you want to emphasize something, use bold style. If you want to refer to the exact name of something in the UI of UBIK, use italic style.
Links
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. ISO15926.
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
Tables
Use the WikiTable like in the following example:
{| class="wikitable" | 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 source-Tag as follows:
<source lang="csharp">
// Hello World in Microsoft C#.
using System;
class HelloWorld
{
public static int Main(String[] args)
{
Console.WriteLine("Hello, World!");
return 0;
}
}
</source>
which will result in
using System;
class HelloWorld
{
public static int Main(String[] args)
{
Console.WriteLine("Hello, World!");
return 0;
}
}
Tips and hints
Attention
Use the Attention template to draw attention to a certain sentence:
{{Attention|Please don't miss this sentence!}}
will result in
 | Please don't miss this sentence! |
Hints
Use the Hint template to outline useful tips and hints:
{{Hint|You should read this, it will simplify your work!}}
will result in
| You should read this, it will simplify your work! |
Colors
Colors should be used very sparingly and only if they really contribute to the better understanding of a text.
Other useful templates
- The KeyPress template allows you to display keyboard commands, so
{{key press|Ctrl|W}}will result in Ctrl+W - Use the UBIK MetaModel template to refer to the data model:
- UBIK® MetaModel
- 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 UBIK Templates
Images
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 |
|---|---|
| UI_ | screenshots of UBIK® Studio, UBIK® Client, Windows (IIS, SQL, Excel, ...) |
| IL_ | Illustrations (diagrams, fractions of slides, ...) |
| SY_ | UBIK® symbols (e.g. images for MetaClass, BASECLASS, relations, ...) |
| IC_ | small graphics (icons, arrows, ...) |
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.
Formats and resolutions
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
| If an image needs to placed in the text, like for emphasizing a certain manual visually, its width should not exceed 700 pixels width in landscape or 700 pixels height in portrait orientation. |
| In the How-To articles 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). |
