Dokumentationen erstellen

Dokumentationen sind Seiten wie diese, welche eine Hilfestellung sein sollen um gewisse Aufgaben zu erfüllen. Folgendes Dokument beschreibt wie solche Dokumentationen erstellt werden können.

WordPress

Dokumentationen werden mit demselben WordPress erstellt, mit dem auch die mobileonly Website verwaltet wird. Um eine neue Dokumentation zu erstellen einfach in dieses WordPress einloggen (bei Fragen an Marcel Herm wenden). In der linken Navigationsleiste gibt es den Punkt “Dokumentationen”. Anklicken, dann landet man bei einer Übersicht aller erstellten Dokumentationen. “Neue Dokumentationen” auswählen und man landet im Editier Dialog für einen neuen Dokumentations-Post.

HTML Konstrukt

Damit die Seitenstruktur über alle Dokumentationen hinweg gleich bleibt, müssen ein paar Punkte beim Erstellen der Dokumentationen beachtet werden. Am einfachsten ist es den Inhalt des Posts über den “Text” Editor (siehe Bild) zu editieren, dort können HTML Tags verwendet werden.

doku_01

Inhaltsverzeichnis

Das Inhaltsverzeichnis bleibt im Blog-Post immer links vom eigentlichen Inhalt zu sehen (außer auf kleinen Bildschirmen) und wird automatisch erstellt. Damit dies funktioniert müssen im Editier Dialog <h3> Tags verwendet werden. Jeder dieser Tags wird als Punkt im Inhaltsverzeichnis gelistet und verlinkt auf den entsprechenden Absatz.

Inhalt

Überschriften

Für Überschriften können <h3> und <h4> Tags verwendet werden, wobei nur <h3> Überschriften im Inhaltsverzeichnis gelistet werden.

Code-Beispiele

Werden Code-Beispiele oder ähnliches dargestellt, so können diese von einem <pre> Block und einem anschließenden <code> Block Umschlossen werden. Vor einem solchen Beispiel empfiehlt es sich das Beispiel anzukündigen:

Beispiel


<p class=“example”>Beispiel</p>
<pre>
	<code>
		 //... Code Beispiel hier
	</code>
</pre>

Um Tabulatoren einzufügen muss &Tab; eingegeben werden. Es wird geparst und durch einen Tabulatorschritt ersetzt.

Bilder

Um Bilder einzufügen müssen sie lediglich per Drag&Drop in das Editierfenster des Beitrags gezogen werden. Es können auch bereits hochgeladene Bilder eingefügt werden: Dafür über dem Text-Editor zum Editieren eines Beitrages auf den Button „Dateien hinzufügen“ klicken. Im Dialog welcher sich dadurch öffnet den Uploadvorgang abwarten (nur bei vorigem Upload eines Bildes), und abschließend das gewünschte Bild auswählen. Rechts im Dialog bei „Ausrichtung“ den Wert „zentriert“ auswählen und zwei Boxen weiter unten die Bildgröße wenn gewünscht auf einen passenden Wert setzen. Abschließend auf „Einfügen“ klicken.

Titelbild

Für das Titelbild (2048 x 490 Pixel) gibt es eine Photoshop Vorlage, welche auf der “moberlin AirPort Extreme” Festplatte unter folgendem Verzeichnis gefunden werden kann (für Zugang zur Festplatte: Stefan Lotzin kontaktieren):

Mobileonly > Dokus > moDocumentation > template.psd

Es sollte wie folgt aussehen:

template

Bevor mit dieser Vorlage ein neues Titelbild erstellt wird sollte das Photoshop File dupliziert werden, um nicht die originale Vorlage zu verändern. Ist die Kopie in Photoshop geöffnet, sollten drei Elemente in der Layer-Ansicht dargestellt werden (siehe Bild). Das oberste Element ist der Ordner “Overlay”, in welchem sich schon der Standard-Text “Doku Titel” befindet. Diesen einfach durch den gewünschten Text austauschen.

doku_04

Jedes Titelbild soll außerdem ein simples, farbiges Icon bekommen, um die einzelnen Dokumentationsposts schnell voneinander unterscheiden zu können. Jeglicher Content der eingefügt wird, also Bilder, Texte, etc. soll unbedingt im “Overlay” Ordner platziert werden, da er dadurch automatisch eine weiße Umrandung erhält die den Content vom Nadelstreif-Hintergrund hervorhebt.

Das fertige Titelbild unter dem Menüpunkt „Datei“ > “Speichern als…” als PNG abspeichern. Um es im Post als Titelbild festzulegen gibt es im WordPress Editierdialog unten rechts die Option “Beitragsbild”. Dort “Beitragsbild festlegen” auswählen, und im erscheinenden Dialog per Drag&Drop das Titelbild in den Browser ziehen, den Uploadvorgang abwarten und abschließend auf “Beitragsbild festlegen” klicken.

Bitte beachten: Der Text im Titelbild sollte dem Titel des Dokumentations-Posts entsprechen, oder eine verkürzte Version des Titels darstellen.

Kategorie

Jeder Dokumentations-Post muss einer (genau einer!) Kategorie angehören. Auf der Übersichtsseite über alle Dokumentationen werden die Vorschau-Elemente aller Posts dann auch nach diesen Kategorien gruppiert. Posts die keiner Kategorie angehören werden auf der Übersichtsseite nicht aufgelistet.
Um eine Kategorie auszuwählen im WordPress Post-Editierdialog rechts das Kästchen “Kategorien” suchen und dort eine geeignete Kategorie auswählen, oder bei Bedarf eine neue erstellen.

Sichtbarkeit

Dokumentationen können vertraute Informationen enthalten, die nur innerhalb von mobileOnly sichtbar sein sollten. Es gibt eine auf IP-Adressen basierende Filterung, welche nur dann alle Dokumentationen anzeigt, wenn man aus dem Firmennetzwerk auf diese Seite zugreift. Eine Dokumentation ist standardmäßig privat. Um sie öffentlich zu machen, muss in der Meta-Box „Sichtbarkeit“ (für gewöhnlich rechts oder unterhalb des Post-Editier Fensters) das Häkchen „Öffentlich“ angehakt werden. Ist diese Optionsbox nicht sichtbar kann sie auf der Editierseite ganz oben rechts unter „Ansicht anpassen“, und dann „Sichtbarkeit“ ausgewählt werden.

Dokumentation veröffentlichen

Ist eine neue Dokumentation fertig, sollte sie bevor sie veröffentlicht wird noch mit der Vorschaufunktion von WordPress überprüft werden. Dafür rechts oben im Post-Editierdialog, im Kästchen “Veröffentlichen” auf “Vorschau” klicken.
Ist alles korrekt, so kann der Button “Veröffentlichen” geklickt werden. Wurde dem Post eine Kategorie zugeteilt, so sollte er nun auf der Übersichtsseite über alle Dokumentationen gelistet werden.