Policies/Wiki Style

Aus Mandriva Community Wiki

Wechseln zu: Navigation, Suche
Welcome to the Mandriva Wiki,
a free documentation project that you can improve.
122 Artikel auf Deutsch.

Inhaltsverzeichnis Einen Account erstellen Installation Hilfe erhalten#Help and contribute helfen und mitarbeiten


Es besteht definitiv die Notwendigkeit der Kohärenz, wenn eine gewisse Anzahl von Leuten untereinander Dokumente redigieren - diese Policy umreißt daher die erforderlichen Mittel zum Editieren in diesem Wiki. Sie benennt ebenso die verschiedenen Templates und Styles, die du benutzen kannst und solltest und auch wann du sie gebrauchen solltest. Sie thematisiert desweiteren die Hierarchie und das Layout des Wiki, generelle Feinheiten der Bearbeitung sowie andere wichtige Informationen.

Wenn du beim Pflegen und Bearbeiten von Dokumenten in diesem Wiki eine wertvolle Hilfe sein willst, und keine Belastung, ist das Lesen dieser Seite für dich ein Muss!

Jeder hat seinen persönlichen Stil. Wir sehen das daran, wie eine E-Mail verfasst ist, wie SPEC-Dateien geschrieben sind und wie Einträge im vorigen Twiki geschrieben waren. Nur um nicht missverstanden zu werden, wir schätzen persönlichen Stil! Wenn nun aber ein ganzes Set von Dokumenten aufrecht erhalten werden soll, an denen jeder mitschreiben kann und das eine Menge Leute lesen, lässt ein gewisses Maß an Konsistenz das Wiki doch erheblich professioneller wirken, außerdem 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 dieses Wiki zu unterlassen.

Inhaltsverzeichnis

Seiten bearbeiten

Fasse getätigte Änderungen zusammen

Schreibe stets eine kurze Zusammenfassung (en) in das gleichnamige Feld unter dem "Bearbeiten von ..."-Bereich. Beschreibe hierin nur knapp, welche Veränderungen du vorgenommen hast, so wie in der Zusammenfassung-Legende (en) beschrieben.

Nutze die Vorschau-Funktion vor dem Abspeichern

Wenn du mit dem Editieren fertig bist, klicke auf "Vorschau zeigen" (en), 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.

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 (<Kommentar> -- Karl Wick 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)

Schlankes Layout

Innerhalb des Wiki gibt es keine Namens- oder Verzeichnishierarchie (mehr), d.h.:

  • der Titel jeder Seite ist zugleich deren Name
  • Vermeide es daher nur {{title}} zu verwenden, die Such-Engine berücksichtigt diese nicht.
  • Benutze statt dessen Kategorien und (Subkategorien), um das Wiki zu strukturieren. Näheres dazu, siehe weiter unten.

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.

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.

'Good Practices'

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.

Für gute Lesbarkeit

  • ein Thema je Artikel: schreibe keinen Artikel über "Bildbearbeitungsprogramme" in dem du dann detailliert auf Gimp, Inkscape usw.. eingehst. Erstelle in solchen Fällen eine Unterseite je Programm und verlinke aus dem Hauptartikel zu diesen. Hilfreich ist es dazu zunächst ein Inhaltsverzeichnis der geplanten Inhalte zu erstellen und anhand dessen zu überlegen, wie sich diese am besten darstellen lassen.
  • sehe je Bildschirmabschnitt einen Titel oder Subtitel vor: das Lesen fällt leichter, wenn du markante Punkte im Blickfeld hast, an denen du dich orientieren kannst.
  • verwende keine eigenen Farben oder Layouts. In diesem Wiki, abgesehen von einigen Ausnahmen wie Home, sind alle Seiten in den selben Farben und dem selben Layout zu halten (Findet man etwa auf Buchseiten fortwährend verschiedene Schriftarten?). Wenn du einfach eine beliebige Farbe für deinen Text verwendest, kann das infolge einer zukünftigen Veränderung von CSS ziemlich besch...eiden aussehen oder zu unvorhergesehenen Resultaten führen (Tipp: Versuche mal einen Link in {{title}} zu integrieren = blauer Link auf blauen Hintergrund, keine gute Idee!).

Für gute Zusammenarbeit

  • lege auch Links zu noch nicht-existierenden Artikeln an (... das kann einfach durch setzen von [[IPv6]] geschehen, wenn die Seite IPv6 noch nicht existiert): das setzt natürlich voraus, zu wissen, welche Artikel bzw. Inhalte noch fehlen, siehe dazu unter Spezial:Gewünschte_Seiten nach.
  • zögere nicht eine neue Unterseite mit vielleicht nur 5 Zeilen anzulegen: das kann gelegentlich der Anfang einer ergiebigen Zusammenarbeit sein. Zumeist habt die Mehrzahl der Leute weniger Hemmungen einen bestehenden Artikel zu bearbeiten, als einen neuen zu kreieren.
  • beginne mit einem Inhaltsverzeichnis: dazu musst du das Thema gründlich durchdacht haben, und falls du nicht fertig wirst, werden auch andere verstehen was du geplant hattest und können die fehlenden Abschnitte ausfüllen.
  • verlinke nicht zu Abschnitten oder Unterabschnitten: ein Link beispielsweise nach RPM_Tutorial#from_sources wird unbrauchbar, sobald der Abschnitt in RPM_Tutorial#from_upstream_sources umbenannt wird.

Style und Templates

Stil sowie die Art und Weise, wie Dokumente geschrieben werden, sind äußerst wichtig. Manche verwenden etwa die Wiki-Sytax, einige andere bevorzugen dagegen die HTML-Syntax. Einige kreieren Seitennamen wie "System Administration", während andere sog. "CamelCase" oder Kurznamen verwenden, wie "SysAdmin" oder "SystemAdministration".

Manche werden bevorzugt "Paragraph"-Tags (<p>) nutzen, auch wenn es gar nicht nötig ist, andere statt dessen "Line break"-Tags (<br>). Manche Leute neigen zu excessivem "bolding" (Fett-Text) und "italics" (Kursiv-Text). All diese Dinge erfordern zumindest soweit normiert zu werden, dass Layout und Aussehen der Inhalte von Seite zu Seite konsistent bleiben.

Templates

MediaWiki erlaubt die Nutzung von Templates, welche es ermöglichen Text konsistent zu stylen, den wir markieren oder hervorheben wollen. Templates werden wie folgt angewendet:

{{template|Text}}

Um beispielsweise das title-Template zu nutzen, um der Beschreibung oder dem Namen einer Seite mehr Ausdruck zu verleihen, verwende:

{{title|Dies ist der Titel des Artikels}}

Eine Liste der derzeit verfügbaren Templates ist hier abrufbar. Von diesen müssen folgende Templates verwendet werden:

  • Template:title - das title-Template wird als aller erstes Element einer Seite verwendet, um den Inhalt der Seite zu umreißen
  • Template:version - ein Template zum Hervorheben einer Versionsnummer; es sollte ausschließlich für Mandriva Linux-Release-Versionsnummern verwendet werden (Bsp. Mandriva Linux 2007)
  • Template:file - ein Template zum Hervorheben von Dateinamen und Verzeichnisnamen (Bsp. /etc/ssh/sshd_config)
  • Template:cmd - ein Template zum Hervorheben eines kurzen Kommandobefehls, der nicht in <pre>-Tags eingeschlossen werden muss, wie urpmi --auto-select; typischerweise innerhalb eines Absatzes verwendet und nicht allein stehend
  • Template:media - ein Template zum Hervorheben eines urpmi-Mediumnamens, der nicht in <pre>-Tags eingeschlossen werden muss, wie /main/release; typischerweise innerhalb eines Absatzes verwendet und nicht allein stehend
  • Template:prog - ein Template zum Hervorheben eines Programmnamens (nicht der Name, unter dem es verwendet wird, sondern unter dem es zu beziehen ist); es sollte immer nur bei der ersten Nennung in einem Absatz benutzt werden (Bsp. sshd)
  • Template:pkg - ein Template zum Hervorheben eines rpm-Packetnamens (Bsp. openssh-server)
  • Template:menu - ein Template zum Hervorheben einer Abfolge von Menü-Klicks (Bsp. Datei > Speichern)
  • Template:var - ein Template zum Hervorheben von Variablennamen, wie bash oder perl usw. (Bsp. $HOME)
  • Template:macro - ein Template zum Hervorheben von rpm-Macros und anderer "%*"-Konstruktionen in spec-Dateien (Bsp. %install oder %mklibname)
  • Template:olang - ein Template zum Erstellen eines Links zu gleichen Inhalten in anderen Sprachen (siehe bspw. Home und Accueil)
  • Template:bug - ein Template zum Erstellen eines Quick-Links zu Bugzilla-Einträgen mit einem kleinen Käfer-Icon davor (Bsp. {{bug|12345}} sähe so Image:bug_small.png Bug #12345 aus)

Alle diese Templates existieren, damit sie benutzt werden und sollten also auch konsistent in der beschriebenen Weise eingesetzt werden. Sie dienen dazu, hier diskutierte Dinge in ihrer Wirkung visuell zu unterstützen und Informationen wie Dateinamen oder Paketnamen hervorzuheben und zu markieren, um sie einfacher unterscheidbar zu machen.

Hinweis: Sofern ein Template ein "="-Zeichen oder "Pipe"-Symbol (|) erfordert, wird es nicht funktionieren, ohne dass '=' oder '|' durch setzen der Tags <nowiki> und </nowiki> neutralisiert werden.

Style

Hier einige Einzelheiten bezüglich des Style von Seiten, die beim Bearbeiten beachtet werden sollten:

  • Es gibt keine Notwendigkeit von Absatz-<p>-Tags; füge lediglich eine Leerzeile zwischen zwei Absätzen ein und das Wiki wird diese automatisch formatieren; vermeide ebenso <br>-Tags.
  • Vermeide es die Wikitext-Notation für bold (Fett-Text) und italic (Kursiv-Text) (''' bzw. '') anstelle von HTML-Codes (<b> bzw. <i>) zu verwenden; die Nutzung von HTML-Codes wird bevorzugt, da man beim Bearbeiten einfacher sehen kann, welches Styling verwendet wird.
  • Leerzeilen zwischen Header-Tags sind wichtig; es sollte exakt 1 leere Zeile vorausgehen (Style-Sheets helfen dabei einen adäquaten Abstand zu setzen, zusätzliche Leerzeilen blähen den Artikel nur unnötig auf).
  • Integriere in Titel keine Links; Links zu anderen Seiten gehören in den Text, nicht in den Titel.
  • Verwende Titel nicht als "Highlighters" oder, um Listen zu erstellen; Titel erzeugen automatisch ein Inhaltsverzeichnis und sollten nur benutzt werden, um logische Text-Einheiten zu separieren, nicht um formatierte Listen zu erstellen.
  • Beim Verlinken zu anderen Artikeln im Wiki, benutze bitte nicht den vollständigen Pfad, benutze vielmehr [[Policies/Wiki_Style|Wiki Style]] (statt bspw. [http://wiki.mandriva.com/Policies/Wiki_Style Wiki Style], damit alles konsistent bleibt, selbst wenn sich der Domain-Name ändert).
  • Verwende in Seiten bitte nicht <a href=...>, wende statt dessen die standardmäßige [http://foo some text]-Notation an.
  • Es sollte stets 1 Leerzeile Textblöcke separieren; das macht es einfacher, den Text beim Bearbeiten zu lesen; stelle also sicher, dass zwischen Absätzen, zwischen Absätzen und <pre>-Tags, Listen, usw. immer 1 Leerzeile gesetzt ist.

Interwiki-Links

Du kannst Interwiki-Links verwenden, um zu anderen Sprachen im Wiki und externen Webseiten zu verlinken, wie etwa Bugzilla. Zum Beispiel wird [[:bugz:12345]] automatisch nach http://qa.mandriva.com/show_bug.cgi?id=12345 verlinken. Wenn du magst, kannst du ihn noch etwas aufhübschen, indem du dies benutzt [[:bugz:12345|Bug #12345]], andernfalls wird der Link so aussehen: bugz:12345. So wendest du den "bugz"-Interwiki-Namen an, um die Bugzilla-URL darzustellen. Anstelle dessen kannst du dich aber auch für das chice {{bug|12345}}-Template entscheiden, wie auch immer, wenn du deinen eigenen Text verwenden, aber den Link beibehalten willst, ist es besser den Interwiki-Link als das Bug-Template zu benutzen, der es dir erlaubt, deinen eigenen Link-Namen einzusetzen (z.B. [[:bugz:12345|Das war ein fieser Bug]]).

Wo immer Interwiki-Links verfügbar sind, benutze sie! Auf diese Weise, sollte sich eine URL irgendwann einmal ändern (z.B. Bugzilla ist nicht mehr unter http://qa.mandriva.com verfügbar), ist es eine Sache ein Record im Interwiki-Database table und ein Template anzupassen, eine ganz andere hingegen, hunderte einzelne individuelle Links abzuändern.

Auch das olang-Template nutzt das selbe Interwiki-Linking. Um von einer Seite zur französischen Version der Seite zu verlinken, würdest du das olang-Template mit dem Interwiki-Link darin so anwenden:

{{olang|[[:fr:Accueil|Franösisch]]}}

Hier spezifiziert der "fr"-Interwiki-Name die französische Version der Seite, in diesem Fall "Accueil" bezeichnet. Damit würdest du nach /fr/Accueil geleitet; siehe Accueil. Aktuell unterstützte Sprachen sind:

  • en - Englisch
  • fr - Französisch
  • de - Deutsch
  • es - Spanisch
  • fi - Finnisch
  • it - Italienisch
  • ja - Japanisch
  • no - Norwegisch
  • pl - Polnisch
  • pt - Portugiesisch
  • ru - Russisch
  • zh - Vereinfachtes Chinesisch
  • zh-tw - Traditionelles Chinesisch

Einfacher ist es allerdings bloß den l10n-Interwiki-Link derart zu benutzen:

[[fr:Accueil|Französisch]]

Wodurch Mediawiki ihn an einer speziellen Stelle positioniert.

Syntax

Hier einige Links zur Wiki-Syntax und was du wie mit Mediawiki anstellen kannst:

Eine neue Seite beginnen

Bevor du eine neue Seite zu einem Thema erstellst, solltest du sicher sei, zuvor gründlich nach einer entsprechenden gesucht zu haben. Möglicherweise existiert eine solche bereits und sollte dementsprechend bearbeitet werden, statt noch eine zweite zu erstellen.

Falls du eine neue Seite erstellen musst, vergewissere dich, welcher Platz ihr gemäß den o.g. Regeln im Wiki zukommt. Wenn du eine Seite falsch oder eine Top level-Seite erstellst, wird sie irgendjemand löschen oder verschieben müssen, was zwar nicht schadet, dich aber frustriert und für jemand anderen extra Arbeit verursacht.

Andere gute Hinweise, die anzumerken wären, findest du in Wikimedia's Neue Seite anlegen-Thema.

Entfernen und umbenennen von Seiten

Bitte entferne oder benennen keine Seiten eigenmächtig um. Solltest du den Eindruck haben, eine Seite sei an einem Punkt, an den sie nicht gehört, wende dich mit deinem Anliegen bitte an die web-discuss-Mailingliste und einer der Administratoren wird die Verschiebung und/oder Löschung der Seite vornehmen, sofern es erforderlich sein sollte.

Für Administratoren enthält Wikimedia einige nützliche Informationen:

Diskussion-Seiten

Diskussion-Seiten sind eine excellente Ressource. Bei Twiki wurden Kommentare von Benutzern innerhalb des Dokumentes selbst platziert (ähnlich einem Changelog, wer was getan hat usw.). Bei Mediawiki ist dies nicht nur unnötig, sondern auch nicht gewollt. Benutzerkommentare auf einer Seite beeinträchtigen deren eigentliche Inhalte, lassen sie ungepflegt und eher dürftig aussehen. Stattdessen sollten die Diskussion-Seiten genutzt werden. Diese Seiten enthalten einen Changelog, wer wann was verändert hat und sie können ebenso Benutzerkommentare zum jeweiligen Thema beinhalten, Anfragen nach zusätzlichen Informationen und so fort. Diskussion-Seiten sind quasi das "Reißbrett" hinter dem tatsächlichen Inhalt.

Anders als noch bei Twiki, gibt es keine Notwendigkeit ein "Changelog" vorzuhalten. Wenn du eine Seite editierst, du etwas in das "Zusammenfassung"-Feld schreibst (z.B. was getan oder geändert wurde), wird jeder, der den Verlauf der Seite einsieht, nicht nur deinen Namen sehen, sondern auch was du in das "Zusammenfassung"-Feld eingetragen hast (dein Changelog-"Eintrag") und wann du die Veränderung vorgenommen hast.

Hinweis: Berücksichtige bitte auch das Wiki Style-Beispiel, welches alle hier diskutierten Markups illustriert.

Extensions

Wir diskutieren (per web-discuss) die Integration verschiedener Mediawiki-Extensions, die hilfreich sein könnten ...

Persönliche Werkzeuge