Artikelstil
Diese Seite stellt eine Empfehlung für den Stil von Wiki-Artikeln dar. Diese Seite ist nicht verbindlich, sondern zeigt auf, was man beim Schreiben eines Wiki-Artikels berücksichtigen sollte.
Struktur
Zum Strukturieren eines Artikels verwendet man Überschriften. Diese Überschriften sollten so wenig wie möglich, aber so tief wie nötig verschachtelt werden. Im Zweifelsfall sollte man die Überschrift einfach weg lassen. Man sollte darauf achten, nicht mehr als drei Ebenen tief zu verschachteln. Besonders komplexe Artikel sollte man besser auf mehrere Einzelartikel im selben Artikel-Namensraum aufteilen.
Die erste Überschrift wird beim Erstellen der Artikel weg gelassen, da sie anhand des Artikel-Seitennamens von der Wiki-Software selbständig erstellt wird. Wenn man eine Überschrift erstellt, fängt man mit der zweiten Ebene an. Überschriften werden direkt über den ersten Absatz und mit einer Zeile Abstand zum vorherigen Absatz gesetzt.
[…] Letzte Zeile des vorherigen Absatzes. == Überschrift == Hier folgt der Inhalt zu dieser Überschrift […]
Hat man in einem Artikel mehr als fünf bis zehn Überschriften, so sollte man das Inhaltsverzeichnis an die Seite verschieben, da sonst nach dem einleitenden Absatz und dem eigentlichen Inhalt des Artikels durch das Inhaltsverzeichnis im alten Wiki-Theme ein sehr großer, unschöner Zwischenraum entstehen würde. Zum Ausrichten den Inhaltsverzeichnisses kann das Vorlagen-Tag {{righttoc}} verwendet werden. Die Vorlage hat beim aktuellen Wiki-Theme keinen Einfluss mehr.
Umzuwandelnde Befehls-Zeilen werden mit einem Leerzeichen jeweils vor und nach der Zeile abgesetzt, ebenso Aufzählungen.
… Text … befehlszeile … Text …
Um den Lesefluss nicht zu beeinflussen, sollte ein Abschnittsende nicht „offen“ sein, nach einem Bild, einer Liste, einer Befehlszeile, o.Ä. noch mindestens ein Absatz kommen, der über mindestens eine Zeile umbricht.
Inhalte
Da jeder Artikel speziell auf die Anforderungen des beschriebenen Programms oder des Themas zugeschnitten werden sollte, kann man sich nur grob an eine Struktur halten. Diese sollte jedoch logisch aufgebaut sein.
- Einleitender Text
- Installation/Beschaffung
- Grundkonfiguration oder -bedienung
- Erweiterte Möglichkeiten oder Bedienung
- Wiki-Links, Web-Links
- evtl. Todo für den Artikel
Einleitender Text
Über den einleitenden Text wird das Artikel-Thema kurz vorgestellt. Dieser Text sollte nicht länger als zwei bis drei Absätze sein, und nicht auf die Konfiguration oder die Beschaffungsmöglichkeiten eingehen, sondern lediglich umschreiben, welches Problem/Programm/Thema dem Wiki-Artikel zu Grunde liegt.
Handelt es sich um ein Programm, das beschrieben wird, bietet sich im einleitenden Text an, ein/das Alleinstellungsmerkmal dieses Programms zu nennen, um einem potentiellen Nutzer zu verdeutlichen, welche Vorteile ihm durch die Verwendung des Programms entstehen.
Handelt es sich um ein Spezialprogramm, für dessen Verwendung gewisse Voraussetzungen erfüllt sein müssen, oder um ein Thema, zu dem tieferes Wissen von Nöten ist, kann man dies im einleitenden Text ebenfalls kurz umreißen. Allerdings sollte man sich auch hier mit der Anzahl der Absätze zurückhalten.
Installation
Der Abschnitt zur Installation sollte – wenn es sich um eine „Standardinstallation“ handelt – die Vorlage {{Installation}} verwenden. Der Vorlagencode wird an der gewünschten Stelle eingefügt.
Um zum Beispiel einen vollständigen Installationsabschnitt inklusive Überschrift und erläuternden Texten für meintollesprogramm aus extra zu erstellen, ist folgendes einzugeben. Weitere Möglichkeiten (unterstützte Repositorys, Zusatzpakete, etc.) der Vorlage werden auf der Vorlagenseite erläutert.
{{installation|repo=extra|paket=meintollesprogramm}}
Müssen für das vollständige Funktionieren nach der Installation des Programms noch Schritte ausgeführt werden, so sind diese ebenfalls anzugeben. Bei Services sind hier zum Beispiel das Aktivieren für den automatischen Start, und das Starten mittels systemctl zu nennen.
Komplexere Installationsvorgänge oder verschiedene Pakete, die zum Installieren zur Auswahl stehen, sind entsprechend zu beschreiben, wobei davon ausgegangen werden kann, dass der Anwender bereits den root-Account verwendet.
Benutzung
Bei einem Artikel zu einem Programm sollte zum Einen die Grundkonfiguration erläutert werden, und zum anderen ein Beispiel mit einer etwas ausführlicheren Konfiguration dargestellt werden. Handelt es sich um ein Programm, das ohne Konfiguration nicht lauffähig ist, so ist dieser Punkt im Artikel auf jeden Fall so ausführlich zu beschreiben, dass danach eine lauffähige Konfiguration vorhanden ist.
Wenn es sich um ein Programm handelt, dass keiner Konfiguration bedarf, so ist dessen Verwendung zu beschreiben, und zwar derart, dass einmal die Standardverwendung beschrieben ist, und einmal eine fortgeschrittene Verwendung dargelegt wird.
Todo und Links
Nach dem eigentlichen Artikel sollte man noch, sofern vorhanden, auf weitere Wiki-Artikel verweisen. Zudem sollte als Weblink zumindest die Homepage des Programmierers oder des Programms angegeben werden. Bei Links zu anderen Seiten sind Sprach-Tags zu verwenden.
== Siehe auch ==
* [[Artikel 1]]
* [[Artikel 2]]
== Weblinks ==
* [http://example.com/deutsch.php Homepage von Programm] {{sprache|de}}
* [http://example.com/englisch.php Weitere Informationen] {{sprache|en}}
Sollte der Artikel unvollständig sein, oder fehlen noch wichtige Angaben, so ist dies vor dem eigentlichen Artikel mittels der Vorlage {{unvollständig}} zu markieren. Wenn man einen unvollständigen Artikel veröffentlicht sollte man also entweder im Text darauf hinweisen, oder nach dem Artikelinhalt eine Überschrift „Todo“ setzen, unter der man auf die Unvollständigkeit eingeht, und Dinge benennt, die noch getan werden müssen, damit der Artikel vollständig ist.
Stil
Ein einheitlicher Stil ist in einer technischen Dokumentation – wie dieses Wiki eine ist – von entscheidendem Vorteil. Wenn alle Artikel identisch strukturiert sind, muss man sich nicht bei jedem Artikel aufs Neue orientieren, sondern kann sich direkt auf den Inhalt des Artikels konzentrieren.
Ansprache
Es hat sich bei technischen Dokumentationen der neutrale Aktivstil bewährt. Dies bedeutet, dass statt „wir“ oder „du“ oder einer passiven Schreibweise „man“ verwendet wird.
- Inklusivstil: „Wir installieren das Programm indem wir …“
- intimer Exklusivstil: „Du installierst das Programm indem du …“
- neutraler Passivstil: „Das Programm wird durch … installiert.“
- neutraler Aktivstil: „Man installiert das Programm indem man …“
Die beiden neutralen Stile kann man auch gleichzeitig im selben Artikel verwenden, ohne einen Stilbruch herbeizuführen.
Syntax
Programme, die in Artikeln erwähnt werden, sollten (nur!) bei der ersten Nennung mit der entsprechenden Wiki-Seite oder der offiziellen Homepage verknüpft werden. Alle weiteren Erwähnungen des Programms werden nicht explizit hervorgehoben.
Dateinamen hebt man hervor, indem man sie in Anführungszeichen, oder in {{ic|mein Code}} setzt. Sollte zu einer Datei ein Wiki-Artikel existieren, so verlinkt man den Dateinamen bei erster Nennung mit dem entsprechenden Artikel, und lässt die Anführungszeichen weg. Im Falle der Verlinkung kann auch der Dateiname weggelassen werden. Es reicht bei sehr langen Pfaden (mehr als drei Unterverzeichnisse), nur bei der ersten Nennung der Datei den vollständigen Pfad anzugeben.
Einzugebende Befehle kann man, wenn es sich nur um einen einzigen Befehl ohne Parameter handelt, direkt im Text notieren, indem man ihn in {{ic|mein Code}} einschließt. Befehlsketten oder Befehle mit Parametern rückt man ein, so dass sie von der Wiki-Software automatisch in eine Befehlszeile umgewandelt werden. Wenn Befehle eine Ausgabe haben, und beides dargestellt werden soll, so bietet sich die Vorlage hc an.
Bei der Notation von Befehlen sollte man das Eingabeprompt weg lassen. Wenn es relevant ist, kann man zwischen root und user unterscheiden, ansonsten soll sich aus dem Kontext ergeben, wie der Befehl ausgeführt werden muss.
Einleitender Text zum folgenden Beispiel. $ dies -als --user $ su Passwort: # dies --als=root # exit $ Abschließender Text zum Beispiel.
Analog hierzu verhält es sich bei der Vorlage hc.
Einleitender Text zum Befehl mit Ausabe
{{hc|ein Befehl|dessen Ausgabe}}
Abschließender Text zum Befehl mit Ausgabe.
Menüpunkte gibt man direkt im Text, umschlossen von Anführungszeichen ein, und verwendet Pfeile, um die Menü-Ebenen zu unterscheiden. Nachfolgendes Beispiel beschreibt, wie man in Firefox einstellt, dass Websites keine eigenen Schriften verwenden dürfen.
Im Firefox-Hauptfenster geht man auf „Bearbeiten → Einstellungen → Inhalt“, und klickt bei „Schriftarten & Farben“ auf „Erweitert“. In dem erscheinenden Dialogfenster entfernt man den Haken vor „Seiten das Verwenden von …“
Sofern ohne Mehrdeutigkeit möglich, kann man lange Optionsbezeichnungen sinnvoll kürzen. Beim „Pfad“ zu der Option wird nicht zwischen Menüs, Untermenüs und Tabs unterschieden.
Grammatik und Orthographie
Niemand ist perfekt, und niemandem wird der Kopf abgerissen, wenn er nicht zu 100 Prozent perfektes Deutsch schreibt. Schließlich sind wir alle nur Menschen, dennoch sollte man darauf achten, nicht „wie Kraut und Rüben“ zu schreiben, und zumindest im Ansatz erkennen lassen, dass man beim Schreiben des Artikels über seine Worte nachgedacht hat.
Dies gilt ebenso für die Rechtschreibung. Alle gängigen Textver- und -bearbeitungprogramme haben eingebaute Rechtschreibprüfungen, auch viele Browser selbst unterstützen dies. Wirklich grobe Schnitzer sind also auf jeden Fall vermeidbar. Bei typischen „Tipp-Rechtschreib-Schwächen“ (Verb groß, Substantiv klein; „di eman“ statt „die man“ – und ähnliches), die man eher zu den Tippfehlern zählen kann, wird aber wohl niemand etwas sagen. Stattdessen sollte man solche Fehler einfach schnell mal eben verbessern, wenn man zufällig auf sie stößt.
Hervorhebungen
Mit Hervorhebungen im Text muss sehr sparsam umgegangen werden, da sie zwar den Textsinn verdeutlichen können, aber bei zu starker Verwendung den Lesefluss stören. Sachlicher Stil zeichnet sich dadurch aus, dass er ohne spezielle Hervorhebungen verständlich ist.
Will man dennoch etwas hervorheben, so ist hierfür die Kursivschreibung (''kursiv'') der Fettschreibung ('''fett''') vorzuziehen. Unterstreichungen sollten auf jeden Fall vermieden werden.
Referenzen und Vermutungen
Bei einer technischen Dokumentation, wie einem Wiki, sollte man vermeiden, sich beim Schreiben auf sich selbst zu beziehen. Wenn eine solche Selbstreferenz nicht vermeidbar ist, so sollte man sie umschreiben („Der Autor hat …“ statt „Ich habe …“).
Eben so wie Referenzen sollte man auch das Anstellen von Vermutungen unterlassen und besser Beschreibungen verwenden. Wenn man einen Artikel schreibt, so sollte man das, was man schreibt, vorher oder während des Schreibens überprüfen.
- Vermutung: „Durch einen Klick auf ‚Run!‘ sollte die Bearbeitung der Daten starten.“
- Beschreibung: „Durch einen Klick auf ‚Run!‘ startet die Bearbeitung der Daten.“
Wenn man eine Aktion ausführt, und sie führt zu einem Resultat, dann schreibt man dies so auch in den Wiki-Artikel. Wenn beim Testen eine Aktion nicht wie erwartet funktioniert, sollte man zuerst ausschließen, ob man beim Testen einen Fehler gemacht hat (ggf. im Wiki/Forum des betroffenen Programms recherchieren), bevor man es in den Artikel schreibt.
Idealer Weise bietet man bei Programmfehlern, die man beim Schreiben bemerkt, auch gleich einen passenden Workaround an. Bei wirklich groben Programmfehlern sollte man den Artikel erst einstellen, wenn das Programm vom Entwickler gefixt wurde, und die gefixte Version in den Arch-Repos vorhanden ist.
Zeichen
Bei Auslassung von Inhalten werden von eckigen Klammern umschlossene Auslassungspunkte verwendet. Allerdings nur, wenn sich die Auslassung zwischen Inhalten befindet. Wenn sich die Auslassung vor oder nach Inhalten befindet, werden die Klammern weg gelassen. Wenn man die Auslassung erklärt, wird diese Erklärung an jeder Stelle von eckigen Klammern umschlossen
… es fehlen […] Inhalte, die irrelevant sind …
Es wird eine Dateiliste ausgegeben: - Datei 1 - Datei 2 - Datei 3 [weitere Dateien]
Wenn Anführungszeichen verwendet werden, sollte man den normalen deutschen Anführungszeichen den Vorrang geben.
„Dieser Text ‚steht in‘ Anführungszeichen“
Die Kodierung der Anführungszeichen und der Auslassungspunkte und der für Menüpfade empfohlenen Pfeile sind in der Wikipedia nachzulesen, und man kann sie sich zur leichteren Verwendung auch mittels Xmodmap auf beliebige Tasten(kombinationen) legen.