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

Überschriften werden ab H2 beginnend eingesetzt. Es sollte möglichst so strukturiert werden, dass nicht mehr Zwischenüberschriften notwendig sind.
Ü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.

Tipp

Um die Formatierung zurück zu setzen finden Sie neben der Schriftfarbe unter mehr Formatierung zurücksetzen.

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

Klickpfade ermöglichen eine Beschreibung ohne Screenshot.

Nachteile:

Änderungen am Klickpfad in der Anwendung müssen nachdokumentiert werden
Sie sind schwierig gut und einheitlich zu beschreiben

Vorteile:

Sie vermeiden den Einsatz von Screenshots.
Sie können mit Icons angereichert werden, die in der Anwendung tatsächlich existieren.
Achten Sie auf eine konkrete Ansprache:

Beispiel:

Klicken Sie in der Navigationsleiste auf den Schraubschlüssel und wählen Sie Rechte & Rollen → Rollen.
Klicken Sie in der Toolbar auf Datensatz anlegen.
Geben Sie dieser neuen Rolle einen Namen.
Wählen Sie die Endpunkte für die diese Rolle gelten soll und die zu gewährenden Autorisierungen.
Speichern Sie die neue Rolle.
Um diese Rolle Benutzern zuzuweisen, folgen Sie dieser Beschreibung → Rechte gewähren.

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 vermieden werden.

Screenshots

Wenn man unvermeidbar 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

Werden Tabellen mit fixer Breite erstellt sollen untereinander platzierte Tabellen die gleichen Breiten haben.

Überschrift	Beschreibung

Überschrift

Beschreibung

->myFuntion(string $message)

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

Codebeispiel in einer Tabelle

Überschrift	Beschreibung

Überschrift

Beschreibung

->myFuntion(string $message)

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

Codebeispiel in einer Tabelle

Codebeispiele

Codebeispiele werden mit dem Makro Code dargestellt werden.

Klicken Sie in der Navigationsleiste auf Plus und wählen Sie Andere Makros.
Suchen Sie nach „Code“. Verwenden Sie bitte folgende Einstellungen:

Beispiel:

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 bspw. mit https://uinames.com/ generiert werden.