SDB:Howto

Jump to: navigation, search

Situation

This SDB (support database) article explains how to write SDB articles.

Procedure

SDB articles are written to give solutions to problems with openSUSE, but also to give more detailed explanations of certain topics. If you have problems with openSUSE, the SDB should be the first place to look for help.

A SDB article should be subdivided into the following parts:

  • Situation
  • Procedure
  • Links

or

  • Symptom
  • Cause
  • Solution
  • Links

Please note that SDB articles - if possible - should always describe the easiest solution. However, it is desirable to also show the fastest solution achievable using the command line or by editing configuration files. In this case, the section "Solution" should be split up into several subsections. Before going into details about the syntax, here is an example: (the template Template:SDB_article is available when creating a new SDB article)


Creating a new article

In your web browser, enter the title of the new article after SDB: in the URL line. If the article doesn't exist yet, click "edit" to create and edit it.

All SDB articles must start with SDB:, this makes searching them easier and constitutes a separate section in the Wiki.

Translations

At present the openSUSE wiki supports multiple languages. If you like, and if you know one of these languages, please translate your article. If you don't, or are not sure if you are fluent enough in the foreign language, please write an email to the opensuse-web mailing list and ask for someone to translate your article.

If you have translated an article, please add the "Interwiki" links at the end of the article. As an example, if you have translated an article from German into English, you add the following at the end of the German article:

[[en:SDB:<articlename>]]

To the english version, add the following:

[[de:SDB:<articlename>]]

Changing existing articles

The SDB namespace is included in our review process. If you edit an article your changes will get reviewed and are visible to all users after review.


Categories

Every SDB article should be accessible through the categories. You can find a list of available categories at Category:SDB. Add the categories at the bottom of the article:

[[Category:SDB:8.0|C]]
[[Category:SDB:Network|C]]

The category is followed by a pipe character and the first character of the title. In the example above, the article is called "Changing NTP Servers", so the pipe character is followed by a "C".

Syntax

Please read our wiki style guidelines to get an overview of how to format the content.

Style

How to address your readers

German SDB articles should use the polite form of address with "Sie", as this is the standard in technical documentation. If this applies to your language, please use the polite form, too. English authors of course don't have that problem ;-).

Terminology in foreign languages

In languages other than English, it is sometimes difficult to do without the original english technical terms. Please try to write such in a way that the broadest group of SDB users will find your article useful, but do not try to find translations when the English terms are commonly understood and used in the target language. A good compromise may be to use both, like in this german example: : "gehen Sie auf die zweite console (Kommandozeile) mit STRG-ALT-F2"

Easy!

Even if using the shell sometimes seems easier, especially for you, please try to keep Linux beginners in mind and also explain how a problem can be solved with YaST2 or other tools.

A good SDB article should describe every single step or link to another article where the specific explanation is provided. So, don't write:

In /etc/inittab, change the default runlevel to 3.

but:

Log in as the root user and open the file /etc/inittab with the
editor of your choice (e.g. vi or pico). Change the line
id:5:initdefault: to id:3:initdefault: so that the system won't boot
into the graphical user interface any more.

This is not meant to be a hard requirement! But please remember that many Linux newbies use openSUSE, too.

Maintenance

It is frequently necessary to adjust SDB articles to new versions of openSUSE, or even to write new ones if the changes are too fundamental. Please try to maintain your SDB articles. As an example, if you notice that your article doesn't apply any more with the latest version of openSUSE, please change the "version" line.

Links