OpenSUSE Style Guide

From openSUSE

Article Titles

The name of your article is also its headline:

• make it clear,
• do not use cryptic abbreviations,
• do not use CamelCase, ie. ThisIsMyGreatArticle (that no search function can find)
• do not repeat the title in the text right below article title,
• do not create your own namespaces.
• use the same style capitalization as Wikipedia. The Mediawiki software works best with this style.

Headings

• Use the = (Heading) markup, not the ''' (bold) markup to create a heading. This way, the table of contents is automatically generated from the headings and that helps readers to go directly to the section of interest.
• Start with double equal sign == not a single =.

Note: single equal sign produces the same text size as the article title, which is not used in any common writing style.

Example:

 ==heading 1==
 ===subheading 1.1===
 ===subheading 1.2===
 ==heading 2==
 ===subheading 2.2===
 ====subheading 2.2.1====
 =====subheading 2.2.1.1=====

• If your text becomes too long, see if it is possible to divide it into subheadings.
• again, use the same style capitalization as Wikipedia.

Mark Up Your Text

Use the MediaWiki formatting and markup features to make your text easier to read.

Filenames and shell commands

• If filename is part of text use a fixed font, source:

<tt>fixed font</tt>

• If it is whole listing, you can use <pre> and </pre> pair of tags, or
• see new features described in Skin Management.

Exploit MediaWiki's Feature Set

Use general HTML formatting sparingly.

Using MediaWiki formatting gives articles a consistent look and feel and makes their source code easier to write, read, and edit. Have a look at the MediaWiki editing help to find out what formatting and markup tools you can use. You may also want to have a look at the source code of a few Wikipedia articles.

Comments

Use the article's discussion page for your comments. Do not clutter the article text.

If you want to communicate with other editors, make comments invisible to the ordinary article reader. To do so, enclose the text that you intend to be read only by editors within tags <!-- -->

Example:

 hello <!--This is a comment.--> world

is displayed as:

hello world

Work in Progress

The openSUSE wiki is work in progress. Comments "Under construction", "not finished" etc. in this context should be used only in seldom occasions when it is important to tell the reader that article doesn't contain complete set of information. For that purpose was created template Expand

Syntax:

        {{Expand}}

Templates

See the Templates list of few often looked for templates.

No Artificial Bloating

Do not create articles that do not contain at least a minimum of relevant information. The Wiki way to suggest that somebody should write an article is to create a link to it. If there are at least two links to the same nonexistent article, it appears on Wanted Pages.