Wiki Guide

---

This guide contains the collected knowledge of the 52°North universe regarding the efficient usage of this wiki. It comprises the following sections:

• Conventions are short and simple "rules" that should be followed for all wiki pages to ensure readability.
• Guidelines are tips and best practices for specific types of pages.

Quick Links

• General documentation index
• Text formatting
• File attachments
• Using Macros aka variables
• Icon library

Conventions

Syntax

• The language is English.
• Use WikiWords intentionally. A WikiWord creates and links to a new topic. Unintentional WikiWords create dead links. Add “!” bevor the CamelCase and it remains a “normal” word, e.g. !GitHub.
• Page title or link to subtopic/subpage should be a speaking titel. No WikiWord! Replace it with a speaking title, e.g. IfgiExternalSemester -> External Semester (ifgi)
• Use raw edit mode not wysiwyg to create and edit topics. wysiwyg can kill the exisitng layout.

Create new topic

• Create Topic with WikiWord (topic name). Do not use more than five words for a heading.
• Replace the first heading WikiGuide with a speaking title. Leave the !! to keep the title out of the table of contents.
• Remove automatically created listings such as:
  • "Web Utilities"
  • "Recent changes in xxx web" (put on an extra page if necessary)
  • "Metadata" heading or comment out
  • "Page contents" in the case of a portal page. The Table of Contents (TOC) can be included on a Regular Page, but should be deleted for overview (portal) pages.
• The start of the page should look like this in raw editing mode:

  ---+ !!Your Speaking page title
  ---
  <sticky><div class="n52TOC">
  %TOC{title="Page contents" depth="2"}%
  </div></sticky>
  
  ---+ Introduction
  
  This topic is about xyz and the intended audience are people who do abc.

• After saving, a descriptive topic add tags! Feel free to add new tags.
• Key words in bold
• The depth parameter will limit the TOC content and title is shown on top of the TOC.
• Projects hosted on github can be enriched with the following line as first line of the topic:

  <a href="https://github.com/52North/PROJECT_NAME">
  <img 
  style="position: absolute; top: 100px; right: 0; border: 0;" 
  src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" 
  alt="Fork me on !GitHub"></a>

  Don't forget to update the href attribute of the link to point to the correct location at github.com.
• Do not create bullet lists deeper than two levels
  • this level is ok
    • not ok anymore (should be used in *exceptional* cases)

Guidelines

Regular Page

A "regular" wiki page describes a specific topic or aspect of a larger topic. Content should be focused and concise, headings clear, use bullets points to reduce text and key words should be bold. The content should not extend past a normal DINA4.

A "regular" wiki page should contain the following sections as first level headlines:

• Introduction (might also be called "About")
• <content headlines>
• <more actual content headlines>
• Contact (who to talk to about the project/software presented on the page)

The "Metadata" heading that was automatically inserted into many old wiki pages is actually deprecated. We would like to have pages that are edited well manually, not generated badly. You can either remove the information completely or comment it out with an HTML comment in the raw view. In the latter case be sure to also add !! to the headline to have it removed from the page contents listing.

Portal Pages

Portal pages are Web Home and Overview Pages like Documentation and BestPractice.

The so called "WebHome" pages exist for each web of the wiki. They are a very important page because they allow new users to find the information they are searching for. Additionally, some projects cover many different wiki pages and have their own "portal" page to provide an overview. For both pages the most important goal is to provide an overview of the existing sub-pages.

To optimize these pages to serve the requirement, try to follow these guidelines:

• Do not add text content to a portal page, except a short introductory text.
• Keep the page so short that users on a regular (or at least you on your own) screen do not have to scroll down to see the end of the page.
• Manually create a list or a table of subtopics using the page titles rather than the raw wiki page names.
• Do not replicate information from subpages.
• Remove automatically created listings such as the "Web Utilities", "Recent changes in xxx web" (you can put these on an extra page), or the "Page contents" (the page should be short enough not to need such a navigational aide).

Step-by-step Instructions

If you put step-by-step instructions, e.g. installation tutorials, into the wiki, please make sure to do the following.

• Use the same level of headline for each step
• Start the headline with "1." or "2)" to display the number of the step. This is important for issue reporting and feedback so that users can clearly state to which step they got.
• If you use sub-steps (e.g. "1.1" or "2.A)") also put them under the same headline level and manually number them
• Consider putting such numbered instructions on to a single wiki page.

Tables

If you want to import large spreadsheets, e.g. from Excel, to the wiki you can use this handy converter: http://www.cbs.mpg.de/internal/fb.twiki.tabler.xhtml

Styling

We have some 52N specific CSS classes in place for some special elements.

• n52TOC: Please use <div class="n52TOC"></div> around the %TOC{}% to ensure a consistent TOC layout all over the wiki. Example: see TOC of this topic.
• n52InfoBox: Provides a rounded corner border with a light blue background color to highlight some infos. Example:
  This is my example info box using <div class="n52InfoBox">.
• n52Warning: Provides a rounded corner border with a light red background color to highlight some warnings. Example:
  This is my example warning box using <div class="n52Warning">.
• n52TwoColumn: Provides a two column style for every content but it requires <div> tags. Example:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sagittis ligula sit amet aliquam condimentum. Nam odio neque, ullamcorper quis accumsan a, vehicula in diam. Maecenas risus dolor, pulvinar eget pharetra eget, dictum non urna. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis elementum condimentum feugiat. Maecenas vitae dictum ante, suscipit porta lacus. Donec convallis dolor vitae pellentesque interdum. Morbi ultrices placerat felis, quis accumsan arcu. Proin at iaculis massa, a mollis sapien. Curabitur sed ipsum porta, ultricies metus eu, tempus ante. Aenean vel purus quam. Cras vel justo vitae sem maximus suscipit eget in risus. Etiam et nulla efficitur, sagittis nulla non, commodo magna. Nunc condimentum sit amet tortor ut fringilla.
• You can combine these CSS classes. Example with n52InfoBox and n52TwoColumn:
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sagittis ligula sit amet aliquam condimentum. Nam odio neque, ullamcorper quis accumsan a, vehicula in diam. Maecenas risus dolor, pulvinar eget pharetra eget, dictum non urna. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis elementum condimentum feugiat. Maecenas vitae dictum ante, suscipit porta lacus. Donec convallis dolor vitae pellentesque interdum. Morbi ultrices placerat felis, quis accumsan arcu. Proin at iaculis massa, a mollis sapien. Curabitur sed ipsum porta, ultricies metus eu, tempus ante. Aenean vel purus quam. Cras vel justo vitae sem maximus suscipit eget in risus. Etiam et nulla efficitur, sagittis nulla non, commodo magna. Nunc condimentum sit amet tortor ut fringilla.