Policies/Wiki Style

Aus Mandriva Community Wiki

Wechseln zu: Navigation, Suche
Mandriva Linux Wiki Style Policy

Achtung: diese Seite ist gerade in Arbeit!


Wenn verschiedene Leute an fremden Dokumenten arbeiten/redigieren, ist es unerlässlich einige Normen zu definieren, welche dies verbindlich regeln, um deren notwendige Kohärenz zu gewährleisten; eben dazu dient diese Wiki Style Policy. Sie beinhaltet deshalb alle wesentlichen Templates und Styles, die du benutzen kannst und solltest und sagt wann du dies tun solltest, desweiteren behandelt sie die zugrunde liegende Hierarchie und das Layout des Wiki, generelle Feinheiten der Bearbeitung und weitere wichtige Informationen.

Sofern du bei der Erarbeitung dieser Dokumentation hilfreich sein und nicht zusätzlich belasten willst, solltest du dies hier aufmerksam lesen!

Jeder hat seinen eigenen Stil; man sieht das an eigentlich jedwedem Text, auch an diesem oder daran, wie Einleitungen im Vorgänger Twiki geschrieben waren. Nur, um nicht missverstanden zu werden, wir schätzen persönlichen Stil durchaus! Wenn hier nun aber ein ganzes Set von Dokumenten entsteht, an denen jeder mitschreiben kann und die eine Menge Leute lesen, lässt ein gewisses Maß an Konsistenz das Wiki doch wesentlich professioneller wirken, zudem resultieren daraus weniger Unordnung, weniger kopierte Inhalte, weniger Frustration, und ein angenehmeres Arbeiten.

Solltest du unfähig oder nicht gewillt sein, den in dieser Policy fixierten Punkten zu folgen, möchten wir dich bitten, das Editieren jeglicher Inhalte des Wikis zu unterlassen.

Inhaltsverzeichnis

[bearbeiten] Seiten bearbeiten

[bearbeiten] Fasse getätigte Änderungen zusammen

Schreibe stets eine kurze Edit summary in das kleine "Zusammenfassung"-Feld unter dem "Bearbeiten von ..."-Textfeld. Beschreibe hierin nur knapp, welche Veränderungen du vorgenommen hast, so wie in Edit summary legend beschrieben.

[bearbeiten] Nutze die Vorschau-Funktion vor dem Abspeichern

Wenn du mit dem Editieren fertig bist, klicke auf "Vorschau zeigen", um zu überprüfen, ob die vorgenommenen Änderungen die beabsichtigte Wirkung zeigen, bevor du sie permanent speicherst. Wiederhole den Editieren/Vorschau-Vorgang ggf. so oft, bis du mit dem Ergebnis zufrieden bist, und erst dann klicke auf "Seite speichern", womit deine Änderungen am Artikel tatsächlich wirksam werden.

[bearbeiten] Signiere deine Kommentare

Signiere auf den "Diskussion"-Seiten der Wiki-Artikel deine Kommentare immer durch setzen von vier Tilde-Zeichen, am besten vom vorstehenden Text abgesetzt durch zwei Bindestriche (-- Tv 11:29, 8 December 2006 (MST)).

Verfügbare Signaturen:

  • drei Tilden (~~~) geben deinen Benutzernamen zurück: Karl Wick
  • vier Tilden (~~~~) geben deinen Benutzernamen plus Zeit/Datum zurück: Karl Wick 07:46, 27 November 2005 (UTC)
  • fünf Tilden (~~~~~) geben einzig Zeit/Datum wieder: 07:46, 27 November 2005 (UTC)

[bearbeiten] Schlankes Layout

Innerhalb des Wiki gibt es keine Hierarchie (mehr), d.h.:

  • der Titel jeder Seite ist zugleich deren Name
  • Vermeide es daher {{title}} zu verwenden, die Such-Engine berücksichtigt diese nicht.
  • Benutze statt dessen Kategorien, um das Wiki zu strukturieren.

Falsch: 

Titel: Releases/Mandriva/2007/Errata
{{title|Mandriva 2007 Errata}}
Dies sind die Errata zu Mandriva 2007

Richtig: 

Titel: Mandriva_2007_Errata
[[Category:Errata]][[Category:2007]]
Dies sind die Errata zu Mandriva 2007

Hierbei sind '_' und ' ' im Titel equivalent.

[bearbeiten] Titel-Wahl

Beim Wählen eines Titels für eine neue Seite bedenke bitte drei Dinge: Ein Titel muss

  • kurz und treffend sein, ohne mehrdeutig zu sein. Berücksichtige dabei auch, wie du ihn von anderen Seiten verlinken willst (etwa ..., lies dazu bitte die [[Mandriva Linux 2007 Errata]]....)
  • den Inhalt der gesamten Seite repräsentieren.
  • verwende 'Mandriva Linux' + Release-Nummer nur in release-spezifischen Fällen. Verwende also nicht "Virtualisierung unter Mandriva Linux 2007", wenn dies für alle Mandriva Linux-Versionen gilt, und verwende auch nicht "Virtualisierung unter Mandriva", denn dieses Wiki behandelt ja offensichtlich nur Mandriva Linux. "Virtualisierung" wäre demzufolge ausreichend.

Als Hilfestellung, überlege dir einfach, was du bei einer Internetrecherche als Suchbegriff eingeben würdest, um zur fraglichen Wiki-Seite zu gelangen.

[bearbeiten] Good Practices

[bearbeiten] Für die Such-Engine

  • benutze keine '=' für Unterüberschriften, beginne immer mit '==': beim Konvertieren in html wird Mediawiki dann h2 statt h1 setzen. Einziger großer Titel sollte der tatsächliche Titel der Seite sein. Das Inhaltsverzeichnis wird dies automatisch berücksichtigen.
  • um eine neue Seite anzulegen, erstelle bitte einen Link auf einer anderen Wiki-Seite (solltest du keine geeignete finden, benutze deine eigene Seite dazu). Erst dadurch wird die Seite für die Such-Engine auffindbar, aber auch für andere, die diese dann verlinken können.
  • ordne neue Seiten von Beginn an wenigstens einer geeigneten Kategorie zu: auf diese Weise nehmen andere eher Notiz davon, dass eine neue Seite hinzugefügt wurde.

[bearbeiten] For readability

  • one topic by article : don't make article about "Graphical programs" on which you deeply explain Gimp, Inkscape, etc. Make one page by program and link to them from the main article. An helper for this is to start by makin the table of contents of the document.
  • try to make one section title or subsection title by screen : it's easier to read when you have "big things" to anchor your vision on.
  • do not attempt to use colors and layout on your own. On this wiki, except a few exceptions such as Home, all the pages must have the same colors and layout (do books have different fonts on each pages ?). If you use a color you want for your text, this could be ugly when changing CSS in the future or lead to unpredictable result (tip : try to use a link in a {{title}} = blue link on a blue background).

[bearbeiten] For collaborative effort

  • make links to non-existing pages (... this can be done with [[IPv6]] ..., when the page IPv6 doesn't exist) : this permits to know which pages are missing in Special:Wantedpages.
  • don't hesitate to create a little page with 5 lines : this can be the start for a collaborative page. People are less afraid of improving a page than creating it from scratch.
  • start with the table of contents : you will have to think properly to the topic and, when not finished, people will understand what you wanted to do and can start filling sections
  • don't link to section or subsection : a link to RPM_Tutorial#from_sources will be broken if the section is renamed to RPM_Tutorial#from_upstream_sources

[bearbeiten] Style and Templates

Style and how documents are written are extremely important. Some people use wiki syntax, some people prefer to use HTML syntax. Some people create page names such as "System Administration" while others would use CamelCase or short names such as "SysAdmin" or "SystemAdministration".

Some people will make use of paragraph tags when it's not required, others will use line break tags when there is no need, etc. Some people prefer excessive bolding and italics. These are all things that need to be "normalized" so that the layout and look of content is consistent from page to page.

[bearbeiten] Templates

MediaWiki allows for the use of templates, which provide consistent styling to text we are trying to mark up or have stand out. Templates are written using:

{{template|text}}

So to use the title template to bring emphasis to the description or name of the page, use:

{{title|This is the title of the page}}

The following templates are available and must be used:

  • Template:title - the title template is used as the very first element of the page to describe the contents of the page
  • Template:version - a template to highlight a version number; this should be used only for Mandriva release version numbers (i.e. Mandriva Linux 2007)
  • Template:file - a template to highlight filenames and directory names (i.e. /etc/ssh/sshd_config)
  • Template:cmd - a template to highlight a quick command that does not need to be wrapped in <pre> tags, such as urpmi --auto-select; typically used within a paragraph and not standalone
  • Template:media - a template to highlight an urpmi medium name that does not need to be wrapped in <pre> tags, such as /main/release; typically used within a paragraph and not standalone
  • Template:prog - a template to highlight the name of a program being mentioned (not the name of a program as it's being used, but as it's being referenced); this should only appear once in a paragraph (the first time it's mentioned) (i.e. sshd)
  • Template:pkg - a template to highlight an rpm package name (i.e. openssh-server)
  • Template:menu - a template to highlight a series of menu clicks (i.e. File->Save)
  • Template:var - a template to highlight variable names, like bash or perl, etc. (i.e. $HOME)
  • Template:macro - a template to highlight rpm macros and other "%*" constructs in spec files (i.e. %install or %mklibname)
  • Template:olang - a template to create a link to similar topics in other languages (see Home and Fr/Maison for an example of how to use this)
  • Template:bug - a template to create a quick link to bugzilla with the little bug icon in front of it (i.e. {{bug|12345}} would look like Bug #12345)

These templates exist to be used and should be used consistently and in the manner noted above. They are used to provide visual queues as to things being discussed and to allow things such as file or package names to stand out, making them easier to distinguish.

Note: If a template has to contain the equal sign (=) or the pipe symbol (|) it won't work unless the "=" or "|" are escaped with the tags <nowiki> and </nowiki>

[bearbeiten] Style

Here are a few items that should be paid attention to in regards to the style of an edited page:

  • There is no need to use paragraph <p> tags; just insert a blank line between paragraphs and the wiki will auto-format; likewise try to avoid <br> tags as well
  • Try to avoid using the wikitext notation for bold and italic (''' and '' respectively); instead use the HTML codes (<b> and <i> respectively); using the HTML codes is preferred as it is much easier to see when editing what styling is being applied
  • Spacing between header tags is important; there should be exactly 1 blank line preceeding them (the style-sheets help to provide adequate spacing, so extra spaces will only serve to enlarge it too much)
  • Do not put links to other pages within a header; links to other pages belong in text, not in headers
  • Do not use headers as "highlighters" or for creating a list; headers automatically create a table of contents and should be used to separate logical sections of text, not to create formatted lists
  • When linking to another article on the wiki, please do not use the full path of the wiki, but instead use [[Policies/Wiki_Style|Wiki Style]] (instead of, for instance [http://wiki.mandriva.com/Policies/Wiki_Style Wiki Style] as that will keep everything consistent even with domain name changes and so forth
  • Please do not use <a href=...> in pages, use the standard [http://foo some text] notation instead
  • There should be 1 blank line separating blocks of text; this makes the text easier to read when editing; so please ensure there is 1 blank line between paragraphs, between paragraphs and <pre> tags, lists, etc.

[bearbeiten] Inter-Wiki Links

You can use Inter-Wiki links to link to other languages on the wiki and to external sites, such as Bugzilla. For instance, using:

[[:bugz:12345]]

Will link to http://qa.mandriva.com/show_bug.cgi?id=12345 automatically. You can pretty this up if you like by using [[:bugz:12345|Bug #12345]] otherwise the link will look like this: bugz:12345. This is using the "bugz" inter-wiki name to represent the Bugzilla url. You can instead opt to use the fancier {{bug|12345}} template instead, however if you want to use your own text but retain the link, it's better to use the inter-wiki link as the bug template gives you no opportunity to create your own link name (i.e. [[:bugz:12345|This was a nasty bug]]).

Where inter-wiki links are available, please use them. This way if a URL ever changes down the road (i.e. bugzilla is no longer available at http://qa.mandriva.com) it's a matter of changing one record in the inter-wiki database table and one template as opposed to potentially hundreds of individual links.

Likewise, the olang template uses the same inter-wiki linking. To link a page to the French version of that page, you would use the olang template with the inter-wiki link inside of it like this:

{{olang|[[:fr:Maison|French]]}}

Here the "fr" inter-wiki name is specifying the french version of the page, called "Maison" in this case. This would take you to /fr/Maison on the site; ie: fr:Maison. Currently supported language-spaces are:

  • de - German
  • en - English
  • es - Spanish
  • fi - Finnish
  • fr - French
  • it - Italian
  • ja - Japanese
  • nb - Norwegian
  • pl - Polish
  • pt - Portuguese
  • ru - Russian
  • zh - Simplified Chinese
  • zh-tw - Traditional Chinese

Though it's simpler to just add the l10n interwiki this way:

[[fr:Maison|French]]

which will make mediawiki place them in a special place.

[bearbeiten] Syntax

Here are some links regarding wiki syntax and the types of things you can do with MediaWiki:

[bearbeiten] Starting a New Page

Before starting a new page, be sure you have searched carefully first before creating the new page. Chances are, the topic already exists and should be edited, rather than duplicated.

If you need to create a new page, be aware of it's place in the "tree" according to the rules noted in the Topic Layout. If you create a page incorrectly, or create top-level page, someone will either have to delete or move it, which does nothing but frustrate you and create extra work for someone else.

Other good ideas to note can be found on Wikimedia's Starting a new page topic.

[bearbeiten] Removing or Renaming Pages

Please don't remove or rename pages on your own. If you feel that a page is in a spot where it does not belong, please email the web-discuss-mailinglist with your request and one of the site administrators will perform the page move and/or deletion if it is required.

For the administrators, Wikimedia has some good information:

[bearbeiten] Talk Pages

Talk pages are an excellent resource. With TWiki, user comments were placed inside the document itself (such as a changelog of who did what, etc). With MediaWiki this is not only not required, but discouraged. User comments on a page detract from the contents of the page itself, making it look dirty and clumsy. Talk pages should be used instead (Talk pages are also known as Discussion pages). These pages can contain a changelog of who made what changes, and they can also contain user comments on the topic, requests for additional information, and so forth. Talk pages are the "drawing board" behind the real content.

Unlike TWiki, there is no need to maintain a "changelog". If, when you are editing a page, you place something in the summary field (i.e. what you did or changed), then anyone viewing the history of the page will not only see your name, but what you put in the summary field (your changelog "entry"), and when you made the change.

Please also refer to en:Policies/Wiki_Style/Example for an example document that illustrates all of the markup discussed here.

[bearbeiten] Extensions

We are discussing (on wiki-discuss) the inclusion of several extensions that could help:

  • video/media inclusion plugin (Under discussion. Requirements : able to play theora files, videos should be viewable with Mandriva Free edition)
  • At least the following extensions are mandatory for any mediawiki site, CharInsert.php for en:MediaWiki:Edittools and Expr.php and ParserFunctions for many recent templates needing the #if conditions: 
require_once( "extensions/CharInsert.php"); in you LocalSettings.php
require_once( "extensions/Expr.php");
require_once( "extensions/ParserFunctions.php");

You can watch the installed extensions at Special:Version. And they are currently not here 16:49, 14 August 2007 (CEST).

Von „http://wiki.mandriva.com/de/Policies/Wiki_Style“
Persönliche Werkzeuge
Andere Sprachen