Hibiscus Benutzer-Handbuch

Konventionen

Layout

Damit die Seiten des Handbuches alle einigermaßen gleich aussehen, sollten die Überschriften ein einheitliches Format besitzen. Das heisst:
1. Jede Seite sollte mit der Überschrift „Hibiscus Benutzer-Handbuch“ - formatiert als H1-Überschrift beginnen.
2. Unmittelbar darunter sollte die Kapitelüberschrift (hier „Konventionen“) - formatiert als H2 - erscheinen.
3. Falls es sich um ein Unter-Kapitel handelt, sollte es als H3-Überschrift folgen.
4. Die Kapitel-Überschriften sollten genauso benannt werden wie im Inhaltsverzeichnis.
5. Für Gliederungen innerhalb des Kapitels können H4-Überschriften genutzt werden.
Falls im Text Bezeichner aus Hibiscus verwendet werden (also z.Bsp. die Beschriftungen von Buttons oder Namen von Dialogen), sollten diese in Anführungszeichen gesetzt werden, um zu verdeutlichen, dass in Hibiscus genau dieser Begriff verwendet wird. Beispiel: Klicken Sie auf den Button „Zurück“.
Klickpfade sollten durch → (Bindestrich, gefolgt von spitzer Klammer nach rechts) dargestellt werden. Beispiel: Klicken Sie im Menü auf „Hibiscus → Einstellungen“.
Besondere Hinweise sollten mit dem Pipe-Symbol „|“ umschlossen werden. Die Wiki-Formatierung erstellt daraufhin eine einspaltige Tabelle für den Absatz und hebt ihn somit farbig und mittels Umrandung hervor. Die Schriftart für Fließtext bleibt jedoch erhalten.
Kommandozeilen-Befehle sollten mit zwei Leerzeichen eingerückt werden. Die Wiki-Formatierung interpretiert das als Code-Fragment und verwendet eine nichtproportionale (dicktengleiche) Schrift wie Courier. Die Formatierung verdeutlicht, dass es sich um einen Befehl handelt.
Soll in einem Satz ein Wort besonders hervorgehoben werden. kann es fett-gedruckt werden. Beispiel: Beachten Sie, dass die Datei hierbei gelöscht wird.
Kursiv-Schrift und Unterstreichungen sollten vermieden werden.

Schreibstil

Der Text sollte in ganzen Sätzen formuliert sein, nicht in Stichpunkten.
Der Leser sollte persönlich angesprochen werden. An ihn wendet sich das Handbuch. Also weder sächliche Schreibweise in der Form „es wird Schaltfläche … geklickt“ oder „wir klicken auf Schaltfläche …“ sondern „Klicken Sie auf Schaltfläche …“.
Der Leser kann mit „Du“ angesprochen werden. Beispiel: „Klicke auf …“ (in einer vorherigen Version dieser Handbuch-Konventionen wurde noch das „Sie“ vorgegeben).
Der Leser sollte Aktionen nach Möglichkeit nicht „müssen“ sondern „können“. Beispiel: „Klicken Sie auf … um das Fenster zu schließen.“ oder „Sie können das Fenster durch Klick auf … schließen“ statt „Zum Schließen des Fensters müssen Sie auf … klicken.“. Es soll dem Leser überlassen bleiben, ob er das tatsächlich möchte.
Ausrufezeichen sollten generell vermieden werden.

Inhalt

Dokumentation sollte nicht wiederholt werden, wenn sie an anderer Stelle im Wiki bereits niedergeschrieben ist. Ein Link mit einem Text wie etwa „Weitere Informationen hierzu finden Sie in [Link].

Screenshots

Hibiscus kann auf verschiedenen Plattformen sehr unterschiedlich aussehen. Daher sollten zumindest die verwendeten Farben und Schriftarten einigermaßen den System-Vorgaben des jeweiligen Betriebssystems entsprechen. Es sollten also beispielsweise keine Screenshots mit großer weißer Schrift auf dunkelgrauem Hintergrund genutzt werden.
Screenshots sollten nur die relevante Funktion bildlich verdeutlichen. Meist genügt daher ein Ausschnitt des Screenshots.