OpenSUSE Style Guide

From openSUSE

This article is in need of attention! You are welcome to improve this article. Refer to this article's discussion page for more information.

The style guidelines cover essentials how to create or edit articles in openSUSE wiki, which should ensure consistent look and feel across the wiki. They are based on similar Wikipedia guidelines.

In case that we didn't cover some case leave a message on a comments and suggestions how to improve guide or on wiki team message board .

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 camel case 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. http://en.opensuse.org/OpenSUSE_Style_Guide

Example:

http://en.opensuse.org/OpenSUSE_Style_Guide
 ==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. You are welcome to help in line with the openSUSE Style Guide. See also the other articles that need to be expanded.

Syntax:

        {{Expand}}

Templates

See the Templates list of few often looked for templates.

Article size

The wiki way to indicate 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 through 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).