SDB:Howto
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.