Help:Style

Wiki

The concept - Namespaces - Categories - Portals - Templates - Icons - Videos - Editing - Style - Cheat sheet

The Style guidelines cover essentials on how to create or edit articles to ensure a consistent look and feel throughout. They are based on similar Wikipedia guidelines. The following guidelines include detailed information on styling openSUSE wiki articles.

General usability

Neutral style

Use a neutral writing style. Avoid the use of personal pronoun "I", "We", etc.

Keep it short and concise

When writing, consider how quickly you decide to read on, or not. Poorly written and overly wordy articles will not be read.

Do not add irrelevant or redundant content. People will read short, clear articles that give the information they need. But they will flee those bloated with irrelevant content.
Use a consistent, non-cluttered format from top to bottom. No one will read a lengthy article broken into sections by miss-matched layouts or colors. Those just make reading slower and serve to drive away the reader.
To make your article useful and popular, keep it short and concise!

See Article development on Wikipedia.

Structure

Title

Title should be clear and short. See Help:Examples of bad article title
Do not use cryptic Acronyms, unless sure they are widely know by the target audience.
Do not use CamelCase. Instead, use spaces.
Use the same capitalization style as Wikipedia.
Do not use a colon as separator in titles as it is used to designate a namespace in MediaWiki.
Avoid the use of special characters. Use [aA-zZ][0-9] characters only.

Section title

All above title guidelines apply to section titles also.
Since section titles form the table of contents a short telegraphic style aids readability and page navigation.
Do not repeat article title in the first section. Redundancy does not encourage further reading.
Do not use About or Introduction as name of the first section. First section of any article is introduction in a topic, so telling that explicitly doesn't bring anything new to the reader.

Headings

Use the = 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 =.

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

Do not put links in headings. Instead, link the word or phrase the first time it appears in the section.
Split very long section into few subsections using subheadings.
Use ---- markup to create a horizontal separator before any level 2 heading (==), as this helps in smooth reading of the article

Example:

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

 ----
 ==heading 3==

Content

openSUSE spelling

openSUSE is the only correct way to spell openSUSE. "OpenSUSE", "openSuSE", OpenSuse" and other variations are all wrongly formatted. As MediaWiki software cannot handle lower-case wiki page title, use Template:Lowercase_title when writing a wiki page whose title begins with "openSUSE".
Do not use trademark characters (such as © or ®) as this impedes the article reading.
Note that the spelling "SuSE Linux" and "SUSE Linux" are deprecated. Unless referring explicitly to an older release of openSUSE (10.1 and earlier release) for historical purposes, SUSE Linux Enterprise Server (SLES) or SUSE Linux Enterprise Desktop (SLED), use "openSUSE".

Duplication

Do not duplicate effort.

Check the openSUSE list of HOWTOs. There is already a large collection of articles. If one exist that covers the subject that you wish to write about then take time to read it and see if it can be improved.
The openSUSE forum has a collection of HOWTOs in the forum Advanced How To/FAQ.
There is also a large collection of HOWTO articles on The Linux Documentation Project.

Acronyms and abbreviations

When introducing new acronyms in an article, use the full name on its first occurrence followed by the abbreviated form inside round brackets. For example: Section titles automatically form the table of contents (TOC).
Avoid complex abbreviations as they make articles more difficult to read.
Always use standard and widely understood abbreviations as innovation may lead to wrong interpretation

Variables

Sometimes, a command input is specific to the user's system, such as system devices or a username. The following conventions are to be used:

<username>, for example in the path command /home/<username>
sdX for storage devices; point is that letter X is capitalized and copy paste will produce an execution error instead of damage.
Tell your reader what to put instead of <username> or sdX, as not everyone is familiar with the writing conventions mentioned here.

Inexperienced user safety

Warning: Be especially careful when giving instructions that have to be run with root user privileges. Commands like dd, rm, fdisk, can do a lot of damage if used without understanding. New users often don't understand, but just copy and paste commands

Use example code which if copied and pasted directly into a command line interface will result in an execution error rather than a disaster.

Wrong!	root # `dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sda`	`/dev/sda` is the first hard disk and exists on every computer.
Good!	root # `dd if=openSUSE-11.2-KDE4-LiveCD-i686.iso of=/dev/sdX`	`/dev/sdX` does not exist in normal installations, and `dd` will return an error about non-existent `/dev/sdX`

Images

Placement

See Image markup for recommendations on the best markup to use. For ideas and examples of how to place images, see Picture tutorial.

Format

Drawings, icons and other such images (basically those with large, simple, and continuous blocks of color) should be in PNG format.
Photos should be in JPEG format.
Animations should be in animated GIF format.

Please note that old versions of articles do not show corresponding old versions of images, but the latest ones, unless the file names of the images have changed.

Colors

If you colorize something see Help:Colors for color tables with the standard openSUSE distribution and website colors.

Comments

Do not clutter article text with editorial comments/questions. Instead, use the article's discussion page.
If you want to communicate with other editors, make comments invisible to the ordinary article reader by using comment tags.

 <!-- This is an invisible comment.  -->

Wanted pages

To indicate that there is a need for some article that doesn't yet exist, create a link to the needed article in the text of an existing article. If there are at least two links to the same nonexistent article, it will be listed on Wanted Pages, which is a source of inspiration for many new wiki authors. While not everything there is really needed, common sense and your expertise will tell you which to choose from the list.

Elements

When writing, ensure to use the following convention.

Wiki markup

While it is possible to use HTML tags to format a page, using the MediaWiki markup will make source text easier to read and edit. You may also look at the Wiki reference card and the source code of a few articles.

Command keys

F5 and Tab

Code: <code>Button to press</code>
Description: Keyboard button to press.
Where: Anywhere

Command path

/usr/src/linux and /etc/SuSE-release

Code: <tt>/path/to/directory/or/file</tt>
Description: Directory path and file path description.
Where: Anywhere

Commands

There are various templates available for shell commands, depending on whether they should be run as a user or as root.

{{Usershell|command=user command}}

user $ user command

{{Usershell|command=user command|output=output}}