Konventionen der Dokumentation

Um ein Einheitliches Bild zu erhalten sollten sich alle Dokumentationen an die folgenden Richtlinien halten.

Sprache

• Förmliche Anrede verwenden wie Sie, Ihre, usw.
• Möglichkeit statt Zwang verwenden. Beispiel: Sie müssen das und das → Sie können mit xy das und das erreichen

Einsatz von Schriften

• Bitte Überschrift-Typen 2 - 3 verwendet werden. Die anderen Überschriften-Größen sehen unschön aus und nehmen Lesbarkeit.
• Überschriften sollen über das Absatz-Menü (oben links) ausgewählt werden und nicht fett markiert oder oder groß gestellt werden.
• Code sollte im Fließtext mit der Festbreitenschriftart gekennzeichnet werden. Neben der Schriftfarbe unter mehr.

Abstände und Umbrüche

Abstände sollten durch die jeweilige Auszeichnung der Textes definiert werden. Das bedeutet, man darf vor oder nach einer Überschrift keine händische Leerzeile einfügen. Die Darstellung in der Bearbeiten-Ansicht kann sich von der tatsächlichen Darstellung unterscheiden. Fließtexte sollen auch ohne Umbrüche geschrieben werden da das Styling der Seite die Umbrüche selbst definiert.

Klickpfade

Generell sollte auf die Beschreibung von Klickpfaden verzichtet werden. Nachteile:

• Änderungen am Klickpfad in der Anwendung müssen nachdokumentiert werden
• Sie verhindern, dass der Anwender die Anwendung versteht
• Sie sind schwierig gut und einheitlich zu beschreiben

Manchmal ist es jedoch notwendig Klickpfade zu beschreiben. In dem Fall bitte so:

Home – Einstellungen – Telefon – auflegen 

Bilder

• Bilder sollten mit der maximalen Breite von 800px und in guter Qualität eingebunden werden.
• Bilder sollen immer in Original-Größe platziert werden.
• Auf einen Rahmen oder Effekt soll verzichtet werden. 
• Screenshots sollten nur den relevanten Bild-Bereich enthalten und dementsprechend auch ohne unschönen Hintergrund eingebunden werden.

Screenshots

Wenn man Screenshots in die Dokumentation einbindet, sollten nur die nötigsten Informationen abgebildet werden. Stellt man einen Datensatz oder eine Tabelle dar, sollte man auf die Breadcrumb oder die Buttons am unteren Bildschirmrand verzichten,

da diese sich ändern könnten. Somit müsste man die Dokumentation anpassen, obwohl sich die eigentliche Thematik nicht geändert hat. Beispiel:

Tabellen

Tabellen sollen mit flexibler Breite erstellt werden. Ziehen Sie die Tabelle nach dem Anlegen auf die gesamte Breite.

$message = 'we ♥ bb';
$myClass = new myClass();
$myClass->myFunction($message);

Codebeispiele

Codebeispiele sollten mit dem Makro Code dargestellt werden. Das findet sich im Menü unter dem Plus-Icon unter Andere Makros (oder strg + shift + a). Dort kann man nach Code suchen. Verwenden Sie bitte folgende Einstellungen:

Beispiel:

// Man beachte die Code-Guidelines
$foo = 'bar';
$fooA = [
  'index' => 'value'
];

Datenschutz

Auf Bildern, Screenshots und Videos dürfen keine Personen oder Gegenstände gezeigt werden die das nicht möchten oder nicht lizenziert sind. Es sollen auch keine Namen von echten Personen verwendet werden. Namen können mit https://uinames.com/ generiert werden.

Verknüpfungen

Confluence bietet die Möglichkeit auf andere Seiten zu verweise wie z.B. Button. Diese Funktion findet sich im Menü unter Verknüpfung einfügen (strg + k). Dort wählen Sie einfach die relevante Seite aus.

Nützliche Shortcuts