Wiki Style Guide

[toc align_right="yes" depth="2"]

DevNet Wiki Style Guide

This is a collection of guidelines for writing wiki pages and articles.

Abbreviations

Abbreviations can be ambiguous. Spell out the term when you use it for the first time followed by the abbreviation in parentheses.

Example: Model View Controller (MVC) is a software's architecture…

Headings and Titles

Page and Category Titles

Use underscores or spaces in your page titles. The wiki engine will convert spaces automatically into underscores in the URL and underscores into spaces in the title.

Avoid special characters that will break the URL.
[TODO: These should be listed; or stated which are allowed (A-Z, a-z, space, underscore, dash(?), Volker]

Headings

Keep headings short and use them to structure your article. Avoid links in headings.

Capitalization

Capitalize all nouns and names in the title and headlines of your article. Avoid using all caps.

Table of Contents

If your article is longer it is easier for the readers if you provide them a table of contents.
[TODO: add TOC section to TextileSyntax and linke here, Volker ]
[TODO It's already styted in WikiSyntax., Gerolf]

Language

Parts of the following apply to all languages, others to English only. Use common sense when adjusting the guidelines to other languages.

General Writing Style

Keep your language understandable and straight to the point and avoid too long and complex sentences.

It is good practice for online writing to subdivide articles with the help of subheadings. Readers will be able to understand your content more easily if it is presented in a scannable manner.

Add a short introduction to the topic to the beginning of your page. Readers will find out quickly if the article covers what they are looking for.

Link to references or related material and check if the links work.

US-English

We prefer US-English, it is commonly used throughout all our sites.

Lists

Use the wiki syntax for both ordered and unordered lists. Start every list item with a capitalized word.

References and Links

coming

Formatting

Use the formatting options the wiki has available. Avoid changing the CSS for single articles since it will interfere with the usability of the site. If you encounter gaps in the current implementation, feel free to report them in the "Beta Forum":http://developer.qt.nokia.com/forums/viewforum/5/.

Exception: workarounds needed to support lacking RTL functionality and language specific font-families
[TODO This now works, Gerolf]