OpenSUSE Style Guide

From openSUSE

This article is in need of attention! This article currently does not meet the standard expected on the openSUSE Wiki. You are welcome to help improve this article. For more information see the Wiki Team.

Please adhere to the following guidelines when creating or editing articles in openSUSE wiki, if in doubt please see Wikipedia guide. This article will try to give the basics and a distinction to Wikipedia. Any suggestions how to improve guide are very welcome. Please use discussion link at the top for the comments.

Article title

The name of your article is also its headline. Make it clear and short, using plain language:

• Avoid cryptic abbreviations when possible, specially if it is available synonym of the similar length.
• Avoid CamelCase. The Mediawiki software can handle spaces in a title. Compare BenefitsOfOpenOffice with Benefits of OpenOffice or Benefits of open office. With CamelCase, it is impossible to tell if the topic OpenOffice refers to the software suite or to offices that maintain openness to the public.
• Avoid naming the first section right below the title with the title. Nobody needs 2 adjacent lines that tell them the same thing, e.g.

Benefits of OpenOffice

Benefits of OpenOffice

• A similar mistake is to repeat the article title by adding "About" or "Introduction" to it. As the example below shows, this is similar to duplication.

Benefits of OpenOffice

About benefits of OpenOffice

• Use the same style capitalization as Wikipedia. It will make starting articles from the links to non existing articles on other pages a breeze.
• Avoid colon as separator in title. See Colon in title.

Section title

• They can be longer than article title, but think of TOC (Table Of Content) layout. It is automatically generated from headings and one very long line followed with a short doesn't help to read it. If possible, select section title to give nice appearance of TOC.
• The capitalization should be the same as article title. First word of the title and proper names should begin with capital letter, nothing else.

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=====

• Very long section is better to split into few subsections using subheadings.
• The capitalization style is the same as Wikipedia. Main reason is the difference in a meaning between proper nouns and nouns. Benefits of Open Office" and Benefits of open office could be 2 different topics. First is the name Open Office (company, newspaper, association), second is general term describing office maintaining something open (structure, access). Using all capitals blurs this distinction.

Use Mediawiki 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.

Have a look at the MediaWiki editing help to find out what formatting and markup tools you can use. You may also look at the source code of a few articles, and don't forget to check new features described in Skin Management.

Examples: File names and shell commands

• If file name is part of the text use a fixed font, source:

<tt>fixed font</tt>

• For a whole listing, you can use <pre> and </pre> pair of tags,

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

This article is a stub! This article needs to be expanded. If you can help please do so in line with the openSUSE Style Guide. If you are looking for something to do, see the other articles that need expanding

Syntax:

        {{Expand}}

Templates

See the Templates list of few often looked for templates.

Article size

The wiki way to inidicate need for some article that doesn't exist yet, is to create a link to article that should be written in the text of existing article. If there are at least two links to the same nonexistent article, it appears on Wanted Pages. Not everything there is really wanted, but common sense and your expertise will tell you what to choose from the list.

The same is valid for the artificial bloating with irrelevant content. You want to make your article popular and people will read more often short articles that give them needed information, than bloated with irrelevant content. See Article development on Wikipedia.

Linking vs. content copy

There are 2 methods to include content from other sources:

• Link to web page with articles that are relevant to your text is lesser work for you. You don't have to think about updating to newer versions. It will be always up to date, but that can ruin your article:
  • if external resource move to another URL (dead link), or
  • if content there changes trough the time so much that it is not the best reference as once it was.
• Copy relevant content form external source. If you decide to use this to assure that text will not change, make sure that you have right to copy (copyright).