Richtlinie

Dies ist eine Empfehlung für das Schreiben eines Artikels. Sie gilt auch für das Vervollständigen beziehungsweise Verbessern eines bestehenden Artikels.

Die Beispiele sollen den Einstieg einfach machen.

Willkommen

Auch dieses Wiki lebt vom Geschrieben und Gelesen werden. Alle sind eingeladen zu schreiben, Korrektur zu lesen und Fehler zu beseitigen.

Es geht um die Weitergabe von Wissen. Also auch wer nicht besonders gut schreiben kann, soll schreiben! Andere Leute werden dann verbessern können und weiteres ergänzen. Bitte habt Mut zum Schreiben und Korrigieren. Es können auch alle Versionen noch eingesehen und notfalls wiederhergestellt werden.

Registrieren (lassen)

Das einfache sich selbst registrieren ist nicht (mehr) möglich. Bitte einfach im Forum oder IRC melden. Es wird dann ein neues Konto für die Benutzung angelegt.

allgemeines Handbuch zum Wiki

Diese Wiki ist ein dokuwiki. Es gibt dazu ein (deuschsprachiges) Handbuch (zur Benutzung) ((englischsprachiges) manual). Das Handbuch erklärt alle üblichen Vorgänge.

Namesraum, Kategorien und Titel der Artikel

Bei der Erstellung eines Artikels stehen die Überlegungen an:

  • In welchen Namensraum soll der Artikel abgelegt sein?
  • In welche Kategorien soll der Artikel einordnet sein?
  • Welchen Titel soll der Artikel haben?

Als Beispiel wird hier ein Artikel über die 'Deinstallation von unter FreeBSD installierten Programmen' verwendet. Folgende Einordnung wäre dann beispielsweise sinnvoll:

Titel Programm deinstallieren
Namensraum HowTo
Kategorien HowTo FreeBSD

Dazu kann es nützlich sein 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 Programm deinstallieren (FreeBSD) denkbar. In der Regel ist es jedoch sinnvoll das Betriebssystem nicht im Namen zu erwähnen, damit Andere den Artikel für andere Systeme ergänzen können.

Neue Artikel sollen im Titel kein Präfix zum Betriebssystem (FreeBSD*, OpenBSD* usw.) enthalten. Bei neuen Artikeln, die dennoch nur für ein bestimmtes Betriebssystem vorgesehen sind, ist der Namen vom Betriebssystem am Ende in Klammern anstellen, zum Beispiel: ISO-Erstellung (OpenBSD).

Artikel anlegen

DokuWiki:Seitennamen#Seite anlegen

Es kann an geeigneter Stelle ein Verweis auf den noch nicht existierenden Artikel angelegt werden.

Ein Artikel Verweis wird mit der folgenden Syntax angelegt:

[[Namensraum:Titel]]
[[Namensraum:Titel|Bezeichnung]]

Verweise zu nicht existierenden Artikel sind rot, anstatt dem üblichen Blau. Beim Anwählen eines solchen Verweises wird Seite zur Bearbeitung (Erstellung) geöffnet. Dort kann dann Text verfasst werden und dann mit Speichern angelegt werden.

Mit Vorschau wird eine Voransicht der Darstellung des (noch nicht gespeicherten) Textes bereitgestellt. So kann vorab die Darstellung getestet und die Anzahl von Änderungen kompakt gehalten werden. Danach kann mit der kurzen Beschreibung der vorgenommen Änderung bei Zusammenfassung mit Speichern der neue Inhalt der Seite abgelegt werden.

Artikel strukturieren

Je nach Umfang des Textes sollte jeder Artikel sinnvoll mit Untergliederungen durch Überschriften strukturiert werden. Lange und nicht gegliederte Texte wirkt abschreckend.

Namensräume

Ein Namensraum, englischsprachig Namespace, ist praktisch wie ein Verzeichnis (Pfad). Ein jeder Artikel kann auch nur in einem Namensraum liegen.

Die Zuordnung zu einem Namensraum klassifiziert den Artikel, auch als „Unterartikel“. Insbesondere beim Schaffung eines neuen Namensraum durch die Verwendung eines bisher noch nicht existierenden Namensraumes, sollte Bedacht walten.

In die Namensräume der BSDs gehören nur sehr wenige Artikel. Ein HowTo ist immer zuerst ein HowTo. Einem Artikel wird die Zuordnung durch die Kategorie für das Betriebssystem zugewiesen.

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

Titel

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 ======

Kategorie

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.

OS Infobox

Betrifft OS:
DragonFlyBSDFreeBSDNetBSDOpenBSD

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.

WM Infobox

Betrifft WM:
KDExfce

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.

Einleitung

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]]

Der Artikel

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.

Zusammenfassung

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.

Syntax-Ergänzungen

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:

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:

Code-Boxen

Es gibt 3 verschiedene Arten von Code-Boxen.

  • code
  • file
  • xterm

code

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

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

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

Boxen für Hinweise

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>

Hinweis

Warnung

Tipp

Wichtig

Stil

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.

Sprache

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.

Anrede

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

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.

Screenshot

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.

Verhaltensregeln

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.