Doku Guideline

rfc... Plan: die Inhaltsüberschriftenliste ist das cheat-sheet, und die ganze Doku, wie man dokumentiert, ist DIESES Dokument.

Werkzeuge

Sammlung, damit der nächste Dokumentierer nicht alle neu zusammensuchen muß

Syntax-Highlighter <> in WordPress

Das Plugin "Crayon" ist vor allem für Quelltexte gedacht, aber für alles, was man eintippen muß, gut geeignet.

Screenshots: Windows, Mac, Unix?

Snagit (Windows) ist ein Screenshothelfer und auch ein Videoprogramm. Es ist leicht zu bedienen und auch die Nachbearbeitung der Screenshots ist prima unterstützt.

Snipping Tool (Windows): wenn es mal ganz schnell gehen soll

Feststehende Ausdrücke

Wir sollten einheitliche Worte verwenden, damit wir die Benutzer nicht verwirren. Wenn es ein gebräuchliches deutsches Wort gibt, nehmen wir das. Dasselbe Ding wird immer mit demselben Begriff bezeichnet. Also nicht: Einmal Button, beim nächsten Mal Schaltfläche.

Die Texte, um die es geht, sind nämlich Anleitungen, keine Erzählprosa. Und es gibt Menschen, die es verwirrend finden, wenn Dinge dauernd ihren Namen ändern, während sie noch dabei sind, herauszufinden, wie irgendwas funktioniert.

Eigentlich selbstverständlich, aber ... veröffentlichte Seiten sollten in Bezug auf Rechtschreibung und Zeichensetzung in Ordnung sein. Das Komma existiert!

Schaltfläche

Also nicht Button, sondern Schaltfläche.

E-Mail

Also nicht E-Post

Uni-Account

Der Uni-Account heißt Uni-Account (nicht ZDV-Account oder sonstwie).

Benutzername

(nicht Username, Login-Name oder wasauchimmer).

Passwort

(zum Uni-Account). Nicht: Password, Kennwort ...

Heimverzeichnis

nicht Heimatverzeichnis, Home ...

Anmelden

nicht Login, authentisieren...

Webseite

Nicht Homepage

Handbuch

(nicht Doku)

Inhaltliches

Wir schreiben für den Benutzer. Der will effizient sein Problem gelöst haben.

Perspektivwechsel: was ist für den Benutzer wichtig?

Unsere Nachrichten sind für Benutzer oft vollkommen unverständlich. Vor dem losschreiben immer denken: Der Benutzer ist auf der Handbuchseite, um Hilfe zu bekommen.

Beiträge nicht recyceln, sondern neuen Beitrag anlegen.

Mehrere Nachrichten zu einem Thema? Besser einen neuen Beitrag anlegen. Das Datum stimmt, die URL stimmt. Und man kann ja IN dem neuen Beitrag auf den alten verweisen...

Beiträge immer mit Weiterlesen-Tag (WordPress)

Immer an die Sammlungsseiten denken: wenn mehr als 2 Zeilen: Weiterlesen-Tag einfügen

URLs: nachhaltig definieren

Beim Anlegen der Seite wird aus der Überschrift eine URL gebastelt. Auf Sonderzeichen achten!

aktive Sprache

Konditional vermeiden. Statt:

"Sie können jede Änderung mit Hilfe der Pfeiltasten in der Werkzeugleiste rückgängig machen oder wiederherstellen."

Besser:

"Sie wollen eine unerwünschte Änderung zurücknehmen? Klicken Sie auf den Pfeil nach links. Mit dem Pfeil nach rechts stellen Sie die zurückgenommenen Text wieder her".

kurze Sätze

sind besser verständlich.

Linktexte = Überschrift der verlinkten Seite (?)

Wenn man etwas verlinkt, tendiert man dazu, das Wort "hier" als Link zu verwenden. Dies ist im Text schlecht lesbar, weil man immer zurückschauen muß, was "hier" in jedem Fall bedeutet. Am wenigsten wird der Benutzer verwirrt, wenn er auf einen Linktext klickt, und dann auf einer Seite mit der Überschrift des Linktextes landet. Statt:

"Infos zum Studium finden Sie hier, Infos zur Historie der Prüfungsordnung können Sie, wenn Sie wollen, sich hier anschauen"

Besser:

• Infos zum Studium
• Historie der Prüfungsordnung

Es sollten immer Suche und Ansprechpartner vorhanden sein. (unten bzw. oben rechts?)

Zusätzlich zum Kontakt oben rechts im unscheinbaren Metamenü. Vor allem, um bei Änderungen einen konkreten Ansprechpartner zu haben.

Dokus von Hiwis sollten als Ansprechpartner den zuständigen Kollegen haben. ??? Was machen wir mit Kollegen, die lieber anonym bleiben wollen?

Gendern

Wir sind dazu angehalten, geschlechtsneutrale Formulierungen zu verwenden.

Das kann man gut finden oder nicht - es soll halt gemacht werden. Es gibt verschiedene Varianten, wie das aussehen kann. Einige Hinweise dazu auf der Seite des Frauenbüros: http://www.frauenbuero.uni-mainz.de/2910.php (rechts unter den weiterführenden Links)

Okay: Mitarbeitende, Studierende usw. Okay, wenn nicht zu häufig: Mitarbeiterinnen und Mitarbeiter Nicht so schön (aber nicht verboten): MitarbeiterInnen ...

Besser (weil natürlicher): In Beispielen, im Text und in Screenshots erscheint ganz selbstverständlich neben Beispielstudent Johannes Gutenberg auch Frau Prof. Dr. Testerin ... und umgekehrt. Oder so ähnlich. Man kann da durchaus kreativ sein, ohne die Sprache komplett unverständlich zu gestalten. Zusätzlich, immer wo es passend ist, die neutralen Formen (Mitarbeitende, Studierende usw.) verwenden.

Text sparsam formatieren

Textauszeichnungen sind sparsam zu verwenden. Die Hervorhebung einzelner Wörter beeinflusst den Lesefluss erheblich. Bei kursiven Zitaten und fetten Überschriften ist dies gewollt und sinnvoll. Eine Auszeichnung einzelner Wörter im Text ist dagegen weitestgehend zu vermeiden. Das Unterstreichen von Text ist überhaupt nicht zu verwenden.

Es spricht aber nichts dagegen, besonders wichtige Informationen in Textboxen zu stellen. Dafür gibt es in WordPress und OpenText eigene Styles!

Eine gute Orientierung ist die Hilfe zu Windows/Office etc. (nicht, weil sie so toll ist, sondern vor allem, weil die meisten Leute diese Hilfetexte wahrscheinlich schon mal gesehen haben und ihnen die Konventionen daher vielleicht einigermaßen vertraut sind. Und - schlecht ist sie nicht).

Titel von Schaltflächen, Befehlen, Menüpunkten, Klickfolgen.

Anführungszeichen werden nicht verwendet (jedenfalls nicht für Menüpunkte etc.), weil Sie den Lesefluß hemmen

Also: Klicken Sie auf Datei > Drucken oder

So sieht es aus:

Datei → Drucken

So erzeugt man es:
<span class="quoted-label">Datei</span> → <span class="quoted-label">Drucken</span>

Der Code für den Pfeil: &rarr;
In diesem Augenblick liegen die neuen Formatierungen nur für den Quelltext vor. Nach der Umstellung auf das responsive Layout stehen die Booststrap-Formatierungen zur Verfügung aus denen die folgenden kopiert bzw. abgeleitet sind.

Schaltflächen, Klickfolgen, Menüpunkte

Werden rund umrandet, das geht, indem man im Quelltext die Klasse quoted-label um ein Span schreibt. So sieht es aus:
Gehe zu
So erzeugt man es:

<span class="quoted-label">Gehe zu</span>

Befehle

Dinge, die man eintippt, sollen grau hinterlegt erscheinen und mit dem Tag kbd erzeugt werden:
So sieht es aus:
ls -ltr
So erzeugt man es:

<kbd>ls -ltr</kbd>

Menüpunkte

Werden mit dem Tag code erzeugt
So sieht es aus:
Datei öffnen
So erzeugt man es:

<code>Datei öffnen</code> bzw. in WordPress das Tastaturkürzel Shift - Alt - x

Bildschirmzitate

Wenn man eine Bildschirmansicht beschreibt, um den Benutzer per Text weiterzuführen:
So sieht es aus:
Bild-Details ergänzen Sie das Feld CSS um: spezial
So erzeugt man es:

<code class="code-green">Bild-Details</code>

Abkürzungen, Tipps, Tricks, Kniffe, Hintergrundinfo

Glühlampe, da muß man was verstehen:

Sind noch solche Piktogramme gewünscht oder in Benutzung?

Syntax-Highlighter

<> in wordpress eingeschaltet, in anderen Systemen (Word, Opentext): An Office-Hilfe orientieren

Keine Anführungszeichen

Nicht "Datei" > "Drucken", sondern

Datei → Drucken

Screenshots von reinem Text kennzeichnen

Es ist nicht schön, wenn man Text auf der Seite sieht, versucht, diesen zu kopieren und dann feststellt, daß es sich um ein Bild handelt.

Kurze Eingaben inline formatieren

(weniger als eine halbe Zeile) sollte man die Darstellung Inline verwenden,

Länger als eine halbe Zeile: Blockformatierung!

Shortcodes in rot (WordPress)

Beispiel Inhaltsverzeichnis

Seite formatieren

breite Bilder -> keine rechte Spalte

Modell 1: die rechte Spalte ist abgeschaltet, damit Doku mit großen Bildern den Platz ausnutzen. (Dann sollte an den Seitenbeginn eine Suche die rechtsbündig oben umfließt. Und der Ansprechpartner für die Seite? Ans Ende der Doku?)

textlastige Doku mit rechter Spalte

Der Fließtext liest sich besser, wenn er nicht so breit ist
Modell 2: es sind nur kleine Bilder, die rechte Spalte ist eingeschaltet, Suche und Kontakt sind dort zu finden.

Bilder

Anleitung muß auch ohne Bilder verständlich sein

Wesentliche Infos dürfen nicht ausschließlich in Screenshots enthalten sein. Es muss auf jeden Fall immer möglich sein, den Inhalt auch ohne Bilder nachzuvollziehen. Test: Das Laden von Bildern im Browser abstellen, unwissend stellen, Anleitung lesen. Klappt trotzdem? So soll es sein.

Beschriftung beschreibt das Bild

Text unter Bildern (caption) soll das Bild beschreiben. Nicht irgendwas Anderes. (Das ist das Feld Beschriftung in WordPress)

nächster Schritt in nächsten Absatz

Der nächste Schritt (nach dem Bild) gehört nicht unter das Bild, sondern in den nächsten Absatz.

max. 900 px breit, max. 600. px. hoch

Bilder dürfen maximal eine Breite von 900 Pixeln haben und sollten nicht höher als 600 Pixel sein

900 Pixel werden in den häufig verwendeten 960- und 1024 Pixel-Layouts von Webseiten komplett angezeigt. Die Höhe sollte üblicherweise kleiner sein als der Seitenbereich des Browsers, damit die letzten Zeilen vor und die ersten Zeilen nach dem Bild gleichzeitig zu sehen sind. So wird der Lesefluss durch das Bild nicht komplett unterbrochen und es fällt zudem leichter, Bild und Text in einem Kontext zu setzen.

Fotos:skalieren,jpg, 80% Kompression

Fotografien sind auf das gewünschte Format zu skalieren und als JPEG mit einer Qualität von 80% zu speichern

Unskalierte Bilder von Digitalkameras sind i.d.R. um mehr als den Faktor 10 größer als das für eine Webseite benötigte Bild. Die Übertragung derartiger Bilder verzögert die Anzeige einer Webseite erheblich. Bis auf wenige Ausnahmen ist der Unterschied zwischen einer Qualität von 80 und 100% nicht zu sehen, die höhere Qualität vergrößert aber das Bild um ein Mehrfaches.

Grafiken (Charts, Logos usw.): skalieren, png, höchste Kompression

Bei Bildern mit einheitlichen Farbflächen und harten Farbübergängen sind JPEG-Kompressionsartefakte mit dem bloßen Auge zu erkennen und beeinträchtigen die Qualität des Bildes erheblich. Im PNG-Format treten derartige Artefakte nicht auf, Farbflächen bleiben bis zu ihrem Rand einheitlich und beeinflussen keine Nachbarfarben. Zudem komprimiert das PNG-Format einheitliche Farbflächen deutlich stärker als es mit JPEG möglich ist. Skalierung und Kompression dienen wie beim JPEG-Format der Reduzierung der Bildgröße und damit der schnelleren Anzeige der Webseite.

Screenshots (nicht skalieren, ggf. unskalierter Ausschnitt)

Bildschirmfotos enthalten Text und Bedienelemente, die in Originalgröße auf gute Les- bzw. Erkennbarkeit ausgelegt sind. Jede Skalierung führt zu unleserlich kleinen und verschwommenen Schriften und ist daher zu vermeiden. Bei Bildschirmfotos sollten daher die Fenster vor der Aufnahme des Fotos entsprechend skaliert werden. Ggf. sind Bildschirmfotos zu beschneiden. Bei Webseiten reicht es häufig aus, nur den eigentlichen Seiteninhalt zu verwenden und Bedienelemente und Fensterrahmen des Browsers zu entfernen. Ist es doch notwendig, größere Bildschirmfotos zu skalieren, sind zusätzlich unskalierte Ausschnitte zu verwenden.

Vorschlag: damit man Screenshots erkennt (und nicht versucht, Text zu markieren), sollten diese kenntlich gemacht werden. Zum Beispiel mit dem gleichen grauen Rand, der um die Bilder der Bildergalerie gelegt ist.

Um den grauen Rahmen zu erzeugen, klickt man auf das Bild, dann auf das Stift-Icon und schreibt dort bei den Bild-Details unter Erweiterte Optionen im Feld CSS Klasse verknüpfen gallery-item hinzu.

Hier ein Beispiel, die Seite mit der Widget-Liste

.png, höchste Kompression

Wichtige Elemente hervorheben (Pfeile, Markierungen)

Wichtige Elemente auf Bildschirmfotos sind hervorzuheben

Bildschirmfotos sind häufig sehr komplex. Wichtige Elemente sind daher hervorzuheben bzw. zu kennzeichnen, z.B. durch einen eingefügten Pfeil. Bei mehreren Elementen ist es sinnvoll, verschiedenfarbige Kennzeichnungen zu verwenden und diese im Text zu erwähnen. (Beispiel: »Geben Sie zunächst ihren Namen (grün) und erst anschließend ihre Mailadresse (rot)«)

Hervorhebung im Text benennen

Kein Textfluss um Bilder/Grafiken!

Alle Bildelemente haben gleiche Breite

Auf einer Seite sollten alle Bildelemente die gleiche Breite haben

Durch Elemente mit gleicher Breite wirkt die Seite deutlich ruhiger und ist besser zu lesen. Umläufe, d.h. die Darstellung mehrerer Elemente (Text, Grafik) nebeneinander, sollten vermieden werden (Ausnahme: Tabellen). Wenn notwendig und nicht durch CSS-Anweisungen erzwingbar, können Grafiken durch einen transparenten Rahmen auf die notwendige Größe gebracht werden. Bei Fotografien ist dies nicht möglich, da das JPEG-Format keine Transparenz unterstützt. Rahmen in der Farbe des Seitenhintergrunds haben den Nachteil, dass bei einer Änderung der Hintergrundfarbe der Rahmen sichtbar wird.)

Bilder sollten erkennbar sein (immer mit Untertitel, damit das Bild als solches erkennbar ist)

Hervorhebungen: gleiche Farbe / Form, einen Beispielpfeil vorschlagen?

Die lange Doku