Getting started

Welcome, new editor of the DE4A documentation wiki!

Before you beging adding content, you can familiarise yourself in on this page with some basic wiki rules and functionalities. All the tips and instructions listed below are also applied on this page, so feel free to copy syntax from the page source as needed.

==> Additional help is available in the Wiki cheat sheet, the User's Guide, and the MediaWiki FAQ.

1 Ground rules

#1 Create from search. When you want to create a new page, start by searching the wiki for existing content. If the search yields no results, you will be offered the option to create a new page. If you do, make sure your search was capitalised in Title Case. Make sure to also search the list of Wanted Pages to make use of existing links (where possible) and prevent unwittingly duplicating a page name.

#2 Page names in Title Case. Page names are capitalised using Wikipedia rules. When in doubt, use this Case Converter tool to find the correct capitalisation. Different letter cases produce different wiki pages. For example, "Reference Interaction Patterns" and "Reference Interaction patterns" will lead to two different pages (the former exists on the DE4A wiki, the latter does not and should not, as it does not follow the Title Case capitalisation rule).

#3 Ask for help. Don't hesitate to contact the WP2 Team for advice and support when or before adding your content to the wiki. We're here to think along and help.

2 Creating and editing pages

2.1 Starting a new page

You can create a new page from a search or from a red link. In both cases, please observe the Title Case capitalisation rule (#2) above for naming the page. Page names cannot be edited anymore once created!

==> For more details see Help:Starting a new page.

2.2 Editing

You can edit the contents of a page with the Visual Editor or the Source Editor. The Visual Editor provides a direct visual way to edit pages based on the "what you see is what you get" principle. It contains a handy page searching function when inserting links. Visual editing is chosen by clicking the Edit tab at the top of a page (or on a section-edit link). The Source Editor can be used for additional functionality with such things as categories, hyperlinks, tables and columns, footnotes, inline citation, special characters and so on. You can access the Source Editor by clicking the Edit source tab at the top of a page (or on a section-edit link).

==> For more help with the editing interfaces see Help:Editing_pages and the Visual Editor User Guide.

2.2.1 Links

The most relevant two types of hypertext links in this wiki are internal links to other pages in the same wiki (commonly called "wikilinks") and external links to pages at other websites.

To create a so-called internal link to a page on the same wiki (a "wikilink"), use double square brackets wiki markup, [[like this]]. When you preview or save your changes, you will see a link that can be followed to the target page. If the page exists the link is displayed in blue; if the page does not exist, the link appears red (so the [[like this]] link is actually rendered like this). Following such a "redlink" to a missing page (whether or not it is actually red) will enable you to create the page.

To markup any arbitrary string of text (not necessarily a page title) as a link, use a "vertical bar" or "pipe" character, like this: [[Main Page|our project]] results in the link our project.

The first letter of the link target is usually not case-sensitive, meaning links can be capitalized or not (so How to contribute and how to contribute are equivalent). However, the case of every subsequent letter must match the target page exactly (so How to contribute and How To Contribute are not equivalent). Spaces in the page title may be represented as underscores (so How to contribute and How_to_contribute are again equivalent), but using underscores in links will make them visible in the page text (but this can be prevented by using a "pipe"). Please refer to rule #2 above when naming pages to prevent creating duplicates.

If the page title you are linking to is that of the page you are editing, the result is not a hyperlink at all but simply bold text (for example, on this page the markup [[Getting started]] gives the result Getting started). If you're trying to create a wikilink to the current page, you probably want to link to a specific section or to an anchor within the page. You do that by adding a "#" before the section name: [[#Ground rules]] will lead to the #Ground rules section.

Please note that links open by default in the same browser tab.

==> For more details see Help:Links.

2.2.2 Formatting

Formatting text to bold, italic, bulleted or numbered lists, tables etc. is most easily done in the Visual Editor.

If you prefer to use the Source Editor, you can format your text by using wiki markup. This consists of normal characters like asterisks, apostrophes or equal signs which have a special function in the wiki, sometimes depending on their position. For example, to format a word in italic, you include it in two pairs of apostrophes like ''this''.

==> For more details see Help:Formatting and the Wiki cheat sheet.

2.2.3 Sections

A page can and should be divided into sections, using the section heading syntax. For each page with more than three section headings, a table of contents (TOC) is automatically generated.

Sections are created by creating their headings, as below.

== Section ==
=== Subsection ===
==== Sub-subsection ====

Please do not use only one equals sign on a side (= Heading =). This would cause a section heading to be as large as the page's name (title). The maximum number of equals signs is six. Heading names of sections (including subsections) should be unique on a page. Using the same heading more than once on a page causes problems.

Linking to a section within the same page is done with the [[#Section_name]] syntax. Linking to a section of another page on the same wiki is done by adding the "#" between the page name and the section name: [[Page_name#Section_name]].

Section headers can be links to other pages: [[===This section also has it's own page that can be opened via this link===]]. The recommended practice is to place an excerpt, a summary or an overview of the dedicated page in the section content of the page being linked from.

NEW! Sections can be numbered where necessary. To activate section numbering on a page add this syntax to the page source code (in the source editor):

2.2.4 Categories

In the DE4A wiki we use categories to indicate the status of a page:

Overview of DE4A wiki page categories

Category	Description
Wip	Page labeled as work In progress, not yet ready for review.
Draft	Page labelled as a draft, ready for review.
Released	A reviewed and finished page.

A category label can be added to a page by inserting [[Category:wip]] at the top of the page in the Source Editor.

A category page can be created the same way as other wiki pages; just add Category: before the page title. To avoid extra work, try searching within the wiki before creating a new category. The list of all categories can be found in the #List of pages section of the Special Pages page.

3 Uploading files

3.1 Files

Files can be uploaded via the Sidebar menu (Tools > Upload File) or while using the Visual Editor (Insert function). Files can be max 2MB in size and permitted file types are png, gif, jpg, jpeg, webp. Other files can be referenced via external links. Appropriate attention should be paid at all times to copyright and confidentiality considerations.

3.2 Images

The DE4A wiki includes an extension that makes it possible to display clickable image maps. An image map is a list of coordinates in a specific image, which hyperlinks areas of the image to multiple destinations (in contrast to a normal image link, in which the entire area of the image links to a single destination). For example, an application collaboration diagram may have each component or service hyperlinked to further information about that component or service. The intention of an image map is to provide an easy way of linking various parts of an image without dividing the image into separate image files.

4 Special pages

Special pages are pages generated by the wiki software on demand for special purposes, usually related to project maintenance. They can be found in the Tools section of the Sidebar (located on the left side of every page). Useful DE4A wiki special pages include:

• All pages
• Files
• Wanted pages (red links)

Wireframe Mock-up