Welcome to the Slackware Documentation Project

This is an old revision of the document!


Style guide for articles published at SlackDocs

A few basic rules should be kept in mind when editing pages in this Wiki.

Page editing etiquette

Release the lock

When you click on the “edit” button, you go into “editing mode”. In this mode, page or section is locked to avoid someone else to edit the page at the same time (creating a conflict). If you close your browser window while you are in “edit” mode, the page lock will not be released for a maximum of 15 minutes. Leave the editor using the “cancel” button when you finally decide to not modify the page. This removes the lock, and permits other people to immediately edit the page.

Edit a section, not the whole page

On the right of each page section header, you see the word [edit]. If you click on it to edit the section, you only lock this section of the page which allows other contributors to edit different sections of the page. This is the recommended way for translating pages, fixing typos or just some sentences/words.

Add a summary

In “edit” mode, you can see an entry field “Edit summary” next to the Save/Preview/Cancel buttons. Use a few words to explain what you have modified. This comment will appear in the “old revisions” tab of the page as well as in the recent changes overview.

Minor modifications

When you only fix a typo, change a word, or make global minor modifications, tick the box “Minor Changes” which you find to the right of the “Edit summary” field. Dokuwiki lets us follow page revisions via RSS. By indicating that you made a “minor change” you will not trigger an update to the RSS feed.
In the “old revisions” tab, minor modifications will be mentioned.

Every page may end with this wiki code, especially if you copied a text from an external source:

===== Sources =====

  * principal author
  * contributors

{{tag>list of tags}}

List of reserved words

There is a list of reserved words used by Dokuwiki as shortcut word.

need to explain the use
FIXME
= footer = (with one or many level ===)

Note about "notes"

You can use several visual boxes, like :

note
tip
important
warning

This is the result of :

<note>note</note>
<note tip>tip</note>
<note important>important</note>
<note warning>warning</note>

The button bar at the top of the edit window contains buttons for easy creation of these notification boxes.

Translating a page

The multi-language capability of this Wiki requires that you stick to a few rules:

  • English is the primary language of the Wiki. Every Wiki article must at least have an English version.
  • When you want to translate a page, you must not change the name of the page.
    For example to translate http://docs.slackware.com/slackware:install into Brazilian Portuguese, just add the pt-br: prefix in the URL like this: http://docs.slackware.com/pt-br:slackware:install . Do not change the page name “install” to its Brazilian Portuguese translation of “instalar” ! You should only translate the page's content.
  • If you want to create a new page in your native language, first create the English version of the page using an English word for the page. A page name like “instalar” is not an English word and therefore will not be accepted. You can start with an empty English page if you want, with just a title for example and containing a large notice that you are working on a translated version first. Then, add your language prefix into the page URL, and start writing your document.
A good practice is to put your doc through an automatic translator like http://translate.google.com/, paste the translated English text into the empty English page, and post on the slackdocs mailing list for help to fix the English translation. Creating the English version is a requirement if you want the site editors to accept the article in your own language.
You should add a note or warning to the English version that it is in need of proof-reading and editing.

Pages that require attention from an admin

If you think that a Wiki page (written by somebody else or by yourself) is in need of attention from the admin team, you can add a tag “needs_attention” to that page. This will cause the affected page to show up on the “pages that need attention” page. The admin team will check that page regularly for new entries.

When should you use this? For instance, you find an incomplete or badly written text or even an empty page (this can happen if someone writes a non-english text but does not take action to get a proper english translation arranged). Or perhaps you find spam, or offensive language.
Your observations will help us keep the Wiki clean and high-quality.


In Other Languages
Translations of this page?:
QR Code
QR Code slackdocs:styleguide (generated for current page)