Artikel-Guide

Dieser Artikel soll eine Empfehlung für das Vorgehen beim Schreiben eines neuen Artikels oder dem Vervollständigen eines alten Artikels sein. Durch einfache Syntaxbeispiele ist der Artikel auch für Wiki-Einsteiger geeignet.

Dieses Wiki lebt von den Autoren und Korrekturlesern. Jeder ist herzlich eingeladen, einen Artikel zu schreiben oder auch nur Fehler und Typos zu beseitigen. Nicht jeder ist der geborene Artikelschreiber, aber das ist kein Grund sein Wissen hier nicht weiterzugeben. Es gibt genug Leute, die Artikel überprüfen und Fehler beseitigen oder Ergänzungen einbringen. Also, nur Mut und ran an den neuen Artikel oder die Korrektur. Es gibt auch einen Rettungsanker: Wenn ein Artikel mehr durch Korrektur gelitten hat, als ursprünglich geplant, kann man den alten Versionsstand wieder herstellen und es erneut versuchen.

Zunächst ist es notwendig sich hier anzumelden bzw. ein neues Benutzerkonto anzulegen. Dies ist leider nicht zu vermeiden, um Spam und Werbung aus dem Wiki fernzuhalten. Es ist außerdem ganz angenehm, wenn man mit den Autoren in Kontakt treten kann.

Am Anfang eines Artikels steht die Überlegung, in welchen Namespace der Artikel gehört, in welche Kategorien man den Artikel einordnen will und welchen Titel man dem Artikel gibt. Als Beispiel wird hier ein Artikel über die 'Deinstallation von unter FreeBSD installierten Programmen' verwendet. Folgende Einordnung wäre dann beispielsweise sinnvoll:

Dazu ist es nützlich die Liste der vorhandenen Kategorien einzusehen. Wenn der Artikel sehr umfangreich ist und wenige Parallelen bei der Vorgehensweise zu anderen BSDs bestehen, ist auch ein Titel wie Programme deinstallieren (FreeBSD) denkbar. In der Regel ist es jedoch sinnvoll das Betriebssystem nicht im Namen zu erwähnen, damit andere Autoren den Artikel für andere Systeme ergänzen können.

Nun ist es an der Zeit mit der Arbeit am eigentlichen Artikel zu beginnen. Dafür muss irgendwo ein Verweis auf den noch nicht existierenden Artikel angeleget werden. Alternativ kann der Artikelname auch in die URL eingetragen werden. Ein guter Platz für einen solchen Verweis ist eine persönliche Seite, die man im Namespace wiki:user anlegen kann. So hat ein Autor auch immer eine Liste der von ihm geschriebenen Artikel verfügbar.

Wie jede andere Wiki Seite auch kann die Seite direkt durch angeben der URL erzeugt werden. Im folgenden Beispiel muss lediglich NAME mit dem Benutzernamen ersetzt werden.

http://wiki.bsdforen.de/wiki:user:NAME

Ein Artikel Verweis wird mit der folgenden Syntax angelegt:

[[Namespace:Artikelname]]
[[Namespace:Artikelname|Beschreibung]]

Wenn der Verweis angelegt ist, ist zu sehen, dass er statt dem üblichen Blau, rot eingefärbt ist. Das bedeutet, dass auf eine (noch) nicht existierende Seite im Wiki verwiesen wird. Um den neuen Artikel anzulegen muss nur noch dem Verweis gefolgt werden.

Um den Changelog kompakt zu halten, sollte stets die 'Vorschau' verwendet werden und 'Seite Speichern' nur nach vormaligem Lesens des bearbeiteten Abschnitts betätigt werden.

Je nach Umfang sollten Artikel sinnvoll strukturiert werden. Text als Meterware wirkt abschreckend, deshalb sollte ein Artikel möglichst in leicht verdauliche Happen unterteilt werden.

Als erste Entscheidung bei der Vorbereitung eines Artikels steht der Namespace, zu Deutsch Namensraum, an. Ein Artikel kann nur in einem Namespace liegen, deshalb muss der gewählt werden, der den Artikel am besten klassifiziert.

In die Namensräume der BSDs gehören nur sehr wenige Artikel. Ein HowTo ist immer zuerst ein HowTo. Einem OS wird ein Artikel normalerweise durch die Kategorien zugewiesen.

Die folgenden Namensräume sind bereits eingeführt. Sollte Unklarheit über den „richtigen“ Namensraum bestehen, bitte einfach im Wiki-Diskussionsforum nachfragen.

• Anwendungen
• HowTo
• Kompendium
• Spiele
• Wiki

Da Dokuwiki nicht automatisch den Titel anzeigt sollte der vom Autor selbst am Anfang des Dokuments angegeben werden. Dazu wird eine Überschrift erster Ordnung (H1) verwendet. Der Titel wird gleichermaßen für die Übersichtsseiten der Kategorien benötigt und ist daher zwingend erforderlich.

====== Titel ======

Ans Ende des Artikels sollten die Kategorien eingetragen werden. Wie das geht, verdeutlicht folgendes Beispiel:

{{tag>HowTo FreeBSD NetBSD}}

Hinter dem Schlüsselwort tag> werden von Leerzeichen getrennt, die Kategorien aufgelistet. Kategorien sind nichts anderes als Artikel im Namensraum Kategorie. Die Kategorien werden zur komfortablen Navigation im Wiki verwendet, deshalb ist ihre Verwendung sehr wichtig.

Zur Übersicht gibt es eine Liste der Kategorien.

Bei Artikeln zu Anwendungen ist zu beachten, dass Sie nur in eine Betriebssystem-Kategorie gehören, wenn sie speziell für dieses System programmiert wurden und auch nur dort verfügbar sind.

Betrifft OS:

Da die Kategorien zwar sinnvoll für die Suche, aber visuell nicht schnell erfasst werden lohnt es sich meist am Anfang des Artikels eine Infobox anzulegen, die mit kleinen Icons anzeigt für welche Systeme der Artikel gilt.

{{Infobox|OS|DragonFlyBSD|FreeBSD|NetBSD|OpenBSD}}

Das ganze sieht dann wie rechts zu sehen ist aus.

Betrifft WM:

Artikel können analog zu der Infobox OS für einen bestimmten oder mehrere Window-Manager (X11) gekennzeichnet werden. Die Syntax ist folgende:

{{Infobox|WM|KDE|xfce}}

Folgende Window-Manager werden zur Zeit angezeigt: KDE, xfce, Gnome, e17, Fluxbox

Das Ergebnis sieht man an der rechten Seite.

Als nächstes sollte der Artikel mit dem ersten Kapitel begonnen werden. Das sollte immer eine Einleitung sein, die klärt für wen der Artikel gedacht ist und wovon er handelt. Auf diese Weise wird vermieden, dass ein Leser einen Artikel unnötig liest. Syntaktisch sieht das dann einfach folgendermaßen aus:

====== Titel ======

Text der Einleitung.

Als nächstes empfiehlt es sich auf artverwandte Artikel zu verweisen, die Informationen enthalten die beim eigenen Artikel vorrausgesetzt werden. Es ginge also folgendermaßen weiter:

===== Verwandte Artikel =====

Es empfiehlt sich zu diesem Thema auch folgende Artikel gelesen zu haben.

  * [[howto:Programme installieren]]

Danach kann der eigentliche Artikel beginnen. Je nach Umfang sollten die einzelnen Kapitel in Abschnitte unterteilt werden:

===== Abschnitt =====

Die einzelnen Kapitel können weiter hierarchich unterteilt werden:

====== Titel ======
===== 1. Kapitel =====
==== 1.1. Kapitel ====
==== 1.2. Kapitel ====
===== 2. Kapitel =====

Ab einem Umfang von 3 Kapiteln legt das Wiki automatisch ein Inhaltsverzeichnis zum Artikel an. Eine gute Strukturierung des Artikels erlaubt dem späteren Leser auf diese Weise den effizientesten Zugriff auf die benötigten Informationen.

Einfache Zeilensprünge werden beim Layout des Artikels nicht berücksichtigt, um einen neuen Absatz zu beginnen benötigt man eine Leerzeile. Oft macht es auch Sinn bestimmte Inhalte in Boxen darzustellen. Dazu werden einer Zeile zwei Leerzeichen vorangestellt.

Der Artikel sollte innerhalb des Wikis abgeschlossen sein, das heißt es sollten keine Informationen vorrausgesetzt werden die nicht im Wiki vorhanden sind.

Am Ende des Artikels sollten die Quellen auflistet und weiterführende Verweise angeboten werden, sofern das nicht schon im Artikel selbst geschehen ist.

Zusammengefasst sollte ein Artikel also beispielhaft so aussehen:

====== Titel ======

{{Infobox|OS|DragonFlyBSD|FreeBSD|...}}
Einleigungstext...

===== Verwandte Artikel =====

Das Wissen aus den folgenden Artikeln wird beim Lesen dieses Beitrages vorrausgesetzt:
  * [[howto:foo]]
  * [[howto:bar]]
  * ...

===== Kapitel =====

Erst hier beginnt der eigentliche Artikel...

==== Unterkapitel ====

von diesesen kann es natürlich auch beliebig viele geben...

===== nächstes Kapitel =====

Nicht jeder Artikel ist in einem Kapitel abgeschlossen...

===== Verweise =====
  * Die ... [[http://url|Homepage]].
  * [[freshports>foo/bar]] in den FreeBSD ports.
  * [[pkgsrc>foo/bar]] in Pkgsrc.
  * ....

{{tag>kategorie:HowTo kategorie:DragonFlyBSD ...}}

Vieles ist natürlich optional, wie die verwandten Artikel, die Infobox oder die Unterteilung in Unterkapitel. Der Titel, die Verweise und auch die Kategorien sind allerdings für gewöhnlich obligatorisch.

Es gibt einige für dieses Wiki spezifische Syntax-Elemente, z.B. durch Plugins.

Das Wiki kennt Verweise zu verschiedenen Paketsystemen:

  * [[freshports>graphics/gimp]] (FreeBSD Ports)
  * [[pkgsrc>graphics/gimp]] (Pkgsrc)
  * [[oports>graphics/gimp]] (OpenBSD Ports)

Die Darstellung erfolgt folgendermaßen:

• graphics/gimp (FreeBSD Ports)
• graphics/gimp (Pkgsrc)
• graphics/gimp (OpenBSD Ports)

Folgende Tags werden benutzt, um mit anderen Wikis zu verknüpfen:

  * [[wp>Berkeley Software Distribution]] - englisches Wikipedia
  * [[wpde>Berkeley Software Distribution]] - deutsches Wikipedia

Die Darstellung erfolgt folgendermaßen:

• Berkeley Software Distribution - englisches Wikipedia
• Berkeley Software Distribution - deutsches Wikipedia

Es gibt 3 verschiedene Arten von Code-Boxen.

• code
• file
• xterm

Eine code-Box kann auf 2 verschieden Arten und Weisen erzeugt werden. Durch Voranstellen von 2 Leerzeichen:

  So etwa.

Oder durch die Verwendung eines <code></code> Blocks:

<code>
# rm -rf *
</code>

Das wird dann so dargestellt:

# rm -rf *

Zusätzlich wird für diverse Programmiersprachen Syntax-Highlighting unterstützt. Zum Beispiel für C++:

<code c++>
#include <iostream>

using std::cout;

int main(int argc, char * argv[]) {
	cout << "Hello, World!\n";
	return 0;
}
</code>

Die Darstellung erfolgt folgendermaßen:

#include <iostream>
 
using std::cout;
 
int main(int argc, char * argv[]) {
	cout << "Hello, World!\n";
	return 0;
}

File-Boxen sind mit einem dunkleren Hintergrund hinterlegt um zu zeigen, dass es sich um den Inhalt einer Datei handelt. Die Verwendung erfolgt zum Beispiel so:

<file>
# We don't want to run scripts twice, due to the X11R6 local merge.
local_startup="/usr/local/etc/rc.d"

# console resolution
allscreens_flags="-h 7000 -t off MODE_291"

...
</file>

Dargestellt wird das Beispiel folgendermaßen:

# We don't want to run scripts twice, due to the X11R6 local merge.
local_startup="/usr/local/etc/rc.d"

# console resolution
allscreens_flags="-h 7000 -t off MODE_291"

...

Xterm-boxen sind vor allem für die Darstellung von Shell-Aufrufen gedacht. Innerhalb dieser Boxen ist die Wiki-Syntax immer noch wirksam. Dadurch können Elemente hervorgehoben werden, zum Beispiel so:

<xterm>
# pkg_cutleaves 
Package 1 of 123:
acroread7-7.0.9_2,1 - Adobe Reader for view, print, and search PDF documents (ENU)
acroread7-7.0.9_2,1 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? (cr)
<nowiki>**</nowiki> Keeping acroread7-7.0.9_2,1.

Package 2 of 123:
apache-ant-1.7.0_1 - Java- and XML-based build tool, conceptually similar to make
apache-ant-1.7.0_1 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? (cr)
<nowiki>**</nowiki> Keeping apache-ant-1.7.0_1.

Package 3 of 123:
autoconf-2.13.000227_6 - Automatically configure source code on many Un*x platforms (2.13)
autoconf-2.13.000227_6 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? **a**

<nowiki>**</nowiki> Deinstalled packages:
<nowiki>**</nowiki> Number of deinstalled packages: 0
</xterm>

Das (cr) wird mit einem Symbol für die Enter-Taste ersetzt. Das Ergebnis stellt sich dann so dar:

# pkg_cutleaves 
Package 1 of 123:
acroread7-7.0.9_2,1 - Adobe Reader for view, print, and search PDF documents (ENU)
acroread7-7.0.9_2,1 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? ↵
** Keeping acroread7-7.0.9_2,1.

Package 2 of 123:
apache-ant-1.7.0_1 - Java- and XML-based build tool, conceptually similar to make
apache-ant-1.7.0_1 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? ↵
** Keeping apache-ant-1.7.0_1.

Package 3 of 123:
autoconf-2.13.000227_6 - Automatically configure source code on many Un*x platforms (2.13)
autoconf-2.13.000227_6 - [keep]/(d)elete/(f)lush marked pkgs/(a)bort? a

** Deinstalled packages:
** Number of deinstalled packages: 0

Es gibt ein Plugin um Hinweise besonders hervorzuheben. Es gibt dabei unterschiedliche Arten von Hinweisen.

<note>Hinweis</note>
<note warning>Warnung</note>
<note tip>Tipp</note>
<note important>Wichtig</note>

Mit der Zeit haben sich in diesem Wiki bestimmte Vorgehensweisen etabliert. Wer sich danach richtet erfüllt die Erwartungshaltung der Leser besser und erleichtert auf diese Weise den Zugang zu seinem Artikel.

Ein Autor sollte sich nach bestem Wissen an die Regeln von Rechtschreibung und Grammatik halten. Fremdwörter und Anglizismen sollten nur dann eingesetzt werden, wenn sie mehr Klarheit verschaffen. Das ist meist dann der Fall, wenn sie sich im allgemeinen Sprachgebrauch durchgesetzt haben. Ein solcher Anglizismus ist zum Beispiel das Wort Firewall. Selbst ein Laie wird damit mehr anfangen können als mit dem Wort Brandmauer, das ohnehin selten verwendet wird.

In einem Wiki treffen Menschen unterschiedlicher Herkunft, Altersgruppen und Begabungen zusammen. Nicht jeder kommt mit einem guten Verhältnis zur deutschen Grammatik und Rechtschreibung. Das sollte jedoch niemanden davon abhalten, sein Wissen weiterzugeben. Formale Fehler können auch andere korrigieren.

Eine Umfrage im Forum hat ergeben, dass die überwältigende Mehrheit als Anrede im Wiki das Du bevorzugt. Alternativ kann die Anrede des Lesers auch komplett vermieden werden. Hierzu sei jedoch angemerkt, dass die häufige Verwendung von man nicht als guter Stil gilt. Wer sich der Herausforderung stellt einen Artikel ohne Anrede zu schreiben, sollte also häufiger auf das Passiv zurückgreifen.

Bilder sind niemals Selbstzweck zur bloßen Verschönerung. In HowTos dienen sie als Orientierungshilfe und in der Kategorie Anwendungen vermitteln sie einen Eindruck von den vorgestellten Programmen. Es hat sich eingebürgert Bilder als 180 Pixel breites Thumbnail darzustellen. Diese Größe reicht für gewöhnlich um einen Eindruck davon zu gewinnen was das Bild zeigt.

Ein Link könnte dann wie folgt aussehen:

{{ http://thunar.xfce.org/images/filewindow-1.png?180|Screenshot}}

Das Leerzeichen hinter den geschweiften Klammern dient zur Ausrichtung des Bildes, welches in diesem Fall am rechten Rand angezeigt wird. Die 180 gibt die Pixelbreite an, Screenshot wird als Textbubble angezeigt, wenn man mit dem Mauspfeil über das Bild geht.

Es gibt einige einfache Verhaltensregeln, die eigentlich jeder vernunftbegabte Mensch von sich aus befolgen sollte. Macht aber leider nicht jeder.

• Zusammenfassung
  • Es sollte immer eine kleine Zusammenfassung in das entsprechende Feld geschrieben werden, damit die History nachvollziehbar bleibt.
• Rechtschreibfehler
  • Rechtschreibfehler sollten natürlich sofort korrigiert werden, aber nicht vergessen den kleine Änderung-Haken zu setzen.
• Programme von Drittherstellern
  • Bitte nicht in jedem Artikel, welcher Programme aus den Ports/pkgsrc verwendet, erklären wie man Ports/pkgsrc verwendet. Nur allgemein sagen was zu Installieren ist und eventuell beachtet werden muß. Dies gilt auch für Hinweise zum Aktualisieren von installierten Paketen und Ports/pkgsrc selbst. Es sollte auch nicht der Hinweis gegeben werden, die aktuellsten Ports zu verwenden. Für den Anfänger ist es sicherer, wenn er bei den Release-Ports bleibt, der Fortgeschrittene weiß dies in der Regel selbst.