Regeln für das Schreiben im Check_MK-Handbuch

Check_MK Manual
Letzte Aktualisierung: 27. März 2019

Suche im Handbuch

1. Wer liest das Handbuch?

Welche Typen von Lesern haben wir? In welchen Situationen wird das Handbuch gelesen?

  • Ich suche nach einem geeigneten Monitoringtool. Dabei ist mir wichtig, dass dieses gut ORACLE überwachen kann. Ist Check_MK geeignet?
  • Ich soll in meiner Firma Check_MK übernehmen und will mich gründlich in das Thema einarbeiten und habe auch Zeit dafür (quasi Ersatz für Schulung bei uns).
  • Ich verwende Check_MK und habe ein bestimmtes Problem, etwas funktioniert nicht, wie ich es haben will.
  • Ich bin Anwender von Check_MK. Jetzt möchte ich in das Thema „Verarbeitung von Events" einsteigen und mich in Ruhe in das Thema einlesen.
  • Jemand verwendet schon länger Check_MK und kommt dann auf eine konkrete Frage, z. B. "Wie kann/soll ich ESX überwachen?" oder "Ich habe Dateisysteme, die von einem Host auf einen anderen wandern können und dann UNKNOWN werden. Wie kann ich das lösen?"
  • Ich kenne die verschiedenen Möglichkeiten, Check_MK zu verwenden. Welche davon ist denn die beste / üblichste? Wie soll man es aufziehen? (Best practise)
  • Ich verwende seit längerem die Check_MK Raw Edition. Jetzt überlege ich, ob die Enterprise Edition für mich interessant ist und gucke mir gezielt einige der Features, die diese mitbringt.
  • Anwender der Raw Edition stolpern beim Lesen des Handbuchs immer wieder über Features der Enterprise Edition und werden neugierig.
  • Ich bin Superexperte für Check_MK und möchte Erweiterungen dafür bauen, ich möchte bestimmte Dinge im Check_MK automatisieren, Skripten, etc. (Poweruser)
  • Ich bin Mitarbeiter von MK (oder Partner) und möchte bestimmte Aspekte in Check_MK genau verstehen, um dann meinen Kunden helfen zu können.

Welche Erlebnisse/Gefühle soll der Leser mit dem Handbuch haben (wie wünschen wir uns das)?

  • Ich finde, was ich suche (vollständig).
  • Es ist angenehm zu lesen.
  • Ich finde die Information schnell und kann sie schnell lesen.
  • Es ist hilfreich (Ich hab's genau verstanden. Ich kann es anwenden und auf andere Situationen übertragen.)
  • Die Antwort ist korrekt und präzise.
  • Ich habe (zufällig) etwas Neues und Tolles entdeckt

2. Syntax des Textformates

Die Artikel des Check_MK-Handbuchs sind in einem eigenen Format verfasst, das intern „Nowiki“ heißt, weil es eine ähnliche Syntax hat, wie ein Wiki, aber keines ist. Dieses Format hat für uns den Vorteil, dass wir es um Check_MK-spezifische Makros anreichern können und die Darstellung wo immer nötig flexibel an unser Webseitenlayout angleichen können.

Grundsätzlich ist es ein HTML-Code, in dem bestimmte Makros erlaubt sind, die von der Webseite ersetzt werden. Die Menge an direkt geschriebenem HTML-Code soll aber auf das absolut notwendige begrenzt werden.

Absätze werden durch Leerzeilen voneinander getrennt. Bitte kein <br> oder <p> verwenden.

Der Großteil der Nowiki-Makros wird durch zweibuchstabige Kürzel am Zeilenanfang geschrieben, welche auf einen Doppelpunkt enden.

Die Implementierung der Makroersetzung ist in der Datei htdocs/nowiki_format.inc. Dort kann man Details nachsehen, Erweiterungen einbauen und Bugs beheben.

2.1. Beginn eines Dokumentes

In der ersten Zeile jedes Artikels steht der Titel mit einem TI: und darunter nach DT: das Datum der letzten inhaltlichen Änderung (also nicht nur Beheben von Tippfehlern):

TI:Regeln für das Schreiben im Check_MK-Handbuchs
DT:2016-10-05

Der Titel wird nicht nur im Artikel selbst angezeigt, sondern auch im Inhaltsverzeichnis index, bzw. an allen anderen Stellen, an denen IN: verwendet wird.

Artikel, die noch im Enstehen sind, erhalten anstelle des Datums das Wort draft:

TI:Regeln für das Schreiben im Check_MK-Handbuchs
DT:draft

Daraufhin erscheint oben im Artikel ein entsprechender Hinweis für den Leser.

Wenn es weitere Artikel gibt, die mit diesem irgendwie verwandt oder verschwägert sind, kann man ein SA: (see also) anhängen. Dabei listet man dann die Artikelnamen mit Komma getrennt auf und sie erscheinen in einem Extrakasten oben rechts beim Artikel.

SA:cmc,cmc_migration,cmc_differences

Hinweis: SA: ist seit Ende März 2019 wieder funktionabel und soll auch verwendet werden, wo es sinnvoll erscheint.

2.2. Der Index

Für den Hauptindex index gibt es ein spezielles Makro, welches einen Indexeintrag auf einen Artikel erzeugt und diesen automatisch weglässt, wenn es den entsprechenden Artikel noch nicht gibt. Außerdem wird automatisch der Titel aus dem Artikel geholt. Beispiel:

IN:introduction
IN:introduction_packages
IN:introduction_virt1

Das wird dann zu:


IN: kann auch in einem Mantelartikel verwendet werden, der nur die Einleitung für eine ganze Sammlung von weiteren Artikel ist.

Interne Artikel

Man kann in den Index auch Artikel einhängen, welche nur veröffentlicht werden sollen, sondern nur intern genutzt werden. Dabei handelt es sich zum Beispiel um diesen Artikel hier. Aber auch um Entwürfe, die es noch nicht wert sind, online zu gehen. Dafür gibt es das Kürzel DR:, welches für „Draft“ steht:

DR:syntax

Wird im Testsystem zu:

2.3. Überschriften

Überschriften werden mit H1:, H2: und H3: gekennzeichnet:

H1:Syntax des Textformates
H2:Kürzel am Zeilenanfang
H3:Überschriften

Achtung (2): In Überschriften sind keine Textauszeichnungen wie z. B. <tt> oder dergleichen erlaubt!

Kürzel Bedeutung Kommentar
H1: Überschrift Ebene 1 Diese Überschrift taucht im Inhaltsverzeichnis des Artikels auf und wird automatisch durchnummeriert. Es definiert ein Kapitel. Eine Kapitel braucht nicht unbedingt mit H2: weiter untergliedert zu sein. Falls es das ist, darf zwischen H1: und H2: kein Text stehen.

Achtung: Die Überschrift darf nicht so lang sein, dass es im Inhaltsverzeichnis (Kasten rechts oben) einen Umbruch gibt!

H2: Überschrift Ebene 2 Diese Überschrift wird mit zwei Ziffern nummeriert und taucht ebenfalls im Inhaltsverzeichnis auf.
H3: Zwischenüberschrift Keine Nummerierung. Dient nur der Gliederung. Zwischen einem H2: und dem folgendem H3: darf ein Textkörper stehen. Ein H3: ist aber nur nach einem H2 erlaubt.

2.4. Verweise und Links

Links zu externen Webseiten werden einfach in HTML mit <a href=...> erzeugt. Links zu Seiten im Check_MK-Handbuch schreibt man in Wiki-Manier in eckigen Klammern: [name|Titel]. name ist dabei der Dateiname der Artikeldatei. Wichtig: zwischen [ und ] darf es keinen Zeilenumbruch geben. Der Parser von Nowiki ist nicht so schlau, dass zu erkennen.

Achtung: Wir verwenden kein target=_blank!. Erstens ist das ein Sicherheitsproblem. Zweitens ist das heute nicht mehr üblich. Wenn der Leser eine neue Seite aufmachen will, kann er das selbst entscheiden.

Anker

Anker setzen einen Einsprungpunkt an eine bestimmte Stelle im Artikel, damit man direkt auf diese Stelle verlinken kann. Anker sind normalerweise an Überschriften der Ebene H1: und H2: gebunden, in dem ein beliebiges Tag mit einer Raute angehängt wird:

H1:Der Livestatusproxy#liveproxy

Einen Anker an einer beliebigen Stelle (z. B. auch vor einem H3:) setzt man mit einem AN: am Anfang der Zeile:

AN:logging
H3:Logdateien
Hier kommt der Text zu den Logdateien

Der Verweis auf einen Anker wird einfach an den Namen des Artikel mithilfe einer # Raute angehängt: [notifications#logging|Das Logging]. Bei Verweisen innerhalb eines Artikels nimmt man einfach den einen Namen. Dafür gibt es keine spezielle Syntax.

2.5. Auszüge von Dateien

Dateiinhalte und Mitschnitte von Konsolensitzungen haben eine eigene Syntax und werden strikt unterschieden! Dateiinhalte werden in einen Abschnitt gepackt, der mit F+: beginnt und mit F-: endet. Dem F+: kann optional ein Dateiname angeängt werden. Wichtig: Pfade innerhalb einer OMD-Instanz werden immer als relative Pfade angegeben. Beispiel: das hier...

F+:var/log/cmc.log
2016-10-03 22:54:33 [5] -----------------------------------------------------------------
2016-10-03 22:54:33 [5] Check_MK Micro Core started with PID 17481
2016-10-03 22:54:33 [5] Version 1.2.8-2016.10.03 compiled Mon, 03 Oct 2016 02:35:46 +0000 on trusty-64
2016-10-03 22:54:33 [5] Loaded 0 hosts and 0 services in 0.044 ms.
F-:

... wird so dargestellt:

var/log/cmc.log
2016-10-03 22:54:33 [5] -----------------------------------------------------------------
2016-10-03 22:54:33 [5] Check_MK Micro Core started with PID 17481
2016-10-03 22:54:33 [5] Version 1.2.8-2016.10.03 compiled Mon, 03 Oct 2016 02:35:46 +0000 on trusty-64
2016-10-03 22:54:33 [5] Loaded 0 hosts and 0 services in 0.044 ms.

Innerhalb eines Dateiinhaltes sind erlaubt:

  • Fettschrift mit <b>...</b>
  • Die Hervorhebung einer Passage durch <b class=hilite>...</b>

Das sieht dann z. B. so aus:

var/log/cmc.log
2016-10-03 22:54:33 [5] Check_MK Micro Core started with PID 17481

2.6. Konsolensitzungen

Konsolensitzungen - also Dialoge auf dem Terminal und nur diese - werden mit C+: und C-: eingeschlossen und anders dargestellt als Dateiinhalte. Konsolensitzungen werden NICHT als Screenshots eingebunden! Denn dann sind sie nicht gut änderbar und außerdem kann der Benutzer dann nichts rauskopieren.

Die wichtigste Konvention bei den Konsolensitzungen ist: Zeichen, die der Benutzer eintippt werden in Fettschrift dargestellt. Und zwar ausschließlich diese. Wenn du etwas hervorheben möchtest, dann verwende <b class=hilite>...</b>.

Speziell für Eingabeprompts auf der Shell gibt es dafür ein paar wichtige Makros, die unbedingt verwendet werden sollen:

  • Ein Prompt als root-Benutzer wird durch RP: geschrieben
  • Ein Prompt als normaler Linuxbenutzer wird durch UP: geschrieben
  • Ein Prompt als OMD-Benutzer wird durch OM: geschrieben
  • Ein OMD-Prompt mit einer ganz bestimmten Site-ID wird durch OM(siteid): geschrieben.

Für Dinge wie die Ausgabe von omd status gibt es die Möglichkeit, Buchstaben farbig zu machen:

  • Rote oder grüne Fettschrift mit <b class=red>...</b> bzw. <b class=green>...</b>

Hier Beispiel für die Syntax:

C+:
UP:su -
Password: 〈b〉********〈/b〉
RP:rm -rf /
RP:su - mysite
OM:omd status
omd status
mkeventd:       〈b class=green>running〈/b〉
liveproxyd:     〈b class=green>running〈/b〉
mknotifyd:      〈b class=green>running〈/b〉
rrdcached:      〈b class=green>running〈/b〉
cmc:            〈b class=red>stopped〈/b〉
OM(slave):exit
C-:

Und so wird es dann dargestellt:

user@host:~$ su -
Password: ********
root@linux# rm -rf /
root@linux# su - mysite
OMD[mysite]:~$ omd status
mkeventd:       running
liveproxyd:     running
mknotifyd:      running
rrdcached:      running
cmc:            stopped
OMD[slave]:~$ exit

2.7. Aufzählungen

Für Aufzählungen mit Spiegelstrichen (Bullets) gibt es eine Variante ohne Nummerierung mit LI: und eine mit mit NL::

Das hier sind die Vorteile:
LI:Punkt eins
LI:Punkt zwei

Und hier sind die Schritte zum Einrichten
NL:Mach zuerst dies
NL:und dann das

Das sieht dann so aus:

Das hier sind die Vorteile:

  • Punkt eins
  • Punkt zwei

Und hier sind die Schritte zum Einrichten

  1. Mach zuerst dies
  2. und dann das

Wichtig: Der komplette Text eines Items muss im Quellcode in einer Zeile stehen. Ja - das kann zu langen Zeilen führen. Also fasse dich kurz! Wenn die Zeile zu lang ist, ist das ein guter Hinweis dafür, dass Spiegelpunkte hier garnicht mehr angemessen sondern, sondern normale Absätze der richtige Weg. Spiegelpunktlisten sollen nämlich einen schnellen Überblick geben.

2.8. Tabellen

Für Tabellen gibt es keine eigene Syntax. Es wird einfach HTML verwendet. Mach kein eigenes Styling! Wenn dir die Darstellung von Nowiki nicht gefällt, dann meckere gerne beim Chefdesigner rum, aber bastele trotzdem nix eigenes mit HTML!

Folgende Regeln gelten:

  • Tabellenüberschriften sind optional und werden in <th>...</th> gesetzt
  • Die Elemente <tr>, <th> und <td> sollen jeweils in einer eigenen Zeilen stehen.

Für die <td>...</td>-Elemente gibt es folgende erlaubte CSS-Klassen. Bei Verwendung von mehreren Klassen braucht man natürlich Quotes:

<th> Die Überschrift der Spalten erfolgt ohne Trennlinie
<td class=tt> IDs oder andere Texte, die 1:1 eingetippt, verglichen oder anderweitig stimmen müssen

Breite der Spalten

Die Breite der Spalten wird so gut wie es geht von HTML bzw. nwbook automatisch bestimmt. Meist klappt dies vor allem beim Buch nicht optimal. Daher soll man die Breiten der Spalten auf der Papierversion ausprobieren und dann explizit setzen wie folgt:

<tr>
<th style="width:17%">open</th>
<td>Foo bar</td>
</tr>

Das ganze nur in der ersten Zeile der Tabelle, entweder bei <td> oder bei <th>. Man darf die Breite nur bei n-1 Spalten angeben, nicht für alle. Die letzte bekommt einfach denn Rest.

2.9. Textauszeichnung

Folgende Formatierungen sind im Fließtext erlaubt.

Format Erklärung
<i>text</i> Kursivschrift im Fließtext. Dies wird verwendet bei der Einführung oder erstmaligen Verwendung von Begriffen und bei einer milden Hervorherbung.
<b>text</b> Fettschrift im Fließtext. Dient der deutlichen Hervorhebung. Bitte sehr sparsam verwenden, sonst sieht aus aus wie in den Bilderwitzen von MAD.
<tt>omd config</tt> Zitate von der Kommandozeile, Eingaben, die der Benutzer 1:1 in der GUI eingeben muss: Melden Sie sich als omdadmin mit dem Passwort omd an. Dieser Zeichsatz symbolisiert, dass hier eine exakte Übereinstimming wichtig ist. Der Zeichensatz ist daher auch optimiert für die Erkennung von Unterschieden zwischen O und 0 und dergleichen.

Achtung: <tt> in H1:, H2: und H3 sind nicht erlaubt!

{{Service description}} Zitat eines Textes aus der Check_MK-Benutzer­oberfläche. Dies wird aktuell kursiv dargestellt, aber das kann sich später eventuell ändern. Das ist also nicht das gleiche wie <i>Kursivschrift</i>, auch wenn es erstnmal gleich aussieht.

Wenn etwas gleichzeitig ein Zitat und eine exakte Übereinstimmung bedeutet (z. B. das Zitieren einer ID), dann gewinnt <tt>

{{Global settings|Foo|Bar}} Navigationspfad in der Check_MK-Benutzer­oberfläche. Darstellung ist aktuell Global settings ➳ Foo ➳ Bar. Der Pfad beginnt meist mit dem WATO-Modul. Wir verwenden auch im Deutschen Handbuch immer die Texte der englischen GUI.

Zusätzliche erlaubte Sonderzeichen:

<br> Zeilenumbruch
&shy; Weiches Trennzeichen
&nbsp; Geschütztes Leerzeichen
&#8230; Ellipse (drei Punkte)
&amp; &-Zeichen
&copy; Copyright-Zeichen
&gt; "Größer als"-Zeichen
&lt; "Kleiner als"-Zeichen
 --  Echter Gedankenstrich. Achtung: es ist wichtig, dass vor und nach den Strichen ein Leerzeichen kommt. Des nachfolgende Leerzeichen soll entfallen, falls dort die Zeile zuende ist.

Typographie

Folgende Konstrukte werden automatisch erkannt und typografisch korrekt gesetzt - sowohl in HTML, als auch in LaTeX (im Buch):

z.B. Abkürzung für "zum Beispiel". Es muss im Quelltext genau so geschrieben werden (ohne Leerzeichen)

2.10. CEE und CRE

Manche Abschnitte im Handbuch betreffen nur die  Check_MK Raw Edition oder nur die  Check_MK Enterprise Edition. Im Fließtext werden die Namen einfach durch (CEE) oder (CRE) eingefügt.

Bei ganzen Absätzen, die nur eine Edition betrffen, werden durch ein [CEE] bzw. [CRE] am Anfang des Abschnittes markiert. Das Kürzel steht direkt am Anfang der ersten Zeile des Abschnittes. Wichtig ist dabei, dass er Absatz lang genug ist. Denn das Wiki baut zur Kennzeichnung der Distro links ein Bild ein, dass vom Text umflossen wird. Ist der Absatz zu kurz, kann es zu komischen optischen Auswirkungen kommen.

[CEE] Verwenden Sie den Notificationspooler.  Verwenden Sie den
Notificationspooler.  Verwenden Sie den Notificationspooler.  Verwenden Sie
den Notificationspooler.  Verwenden Sie den Notificationspooler.  Verwenden Sie
den Notificationspooler.  Verwenden Sie den Notificationspooler.  Verwenden Sie
den Notificationspooler.

Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler. Verwenden Sie den Notificationspooler.

2.11. Makros im Fließtext

Makro Erklärung
(OK) (WARN) (CRIT)
(PEND) (UNKNOWN)
(UP) (DOWN) (UNREACH)
Bezeichnet Monitoringzustände. Die Darstellung ist: OK WARN CRIT PEND UNKNOWN UP DOWN UNREACH
(CEE) Bezeichnet die Check_MK Enterprise Edition. Darstellung:  Check_MK Enterprise Edition
(CRE) Bezeichnet die Check_MK Raw Edition. Darstellung:  Check_MK Raw Edition
ICON[icon_help.png] Dient dem Einbetten von kleinen Bildern aus der GUI, die so skaliert und positioniert werden, dass sie in den normalen Textfluss passen. Wenn die Icons zur Illustration eingesetzt werden, sollen sie immer vor dem Begriff stehen, z. B. wie bei der Onlinehilfe. Man kann damit auch Screenshots von Knöpfen wie einbinden.
(NEW) Ein Hinweis auf einen neuen Artikel. Dieser Hinweis ist für das Inhaltsverzeichnis (index) vorgesehen.
VERSION[1.4.8i2] Hinweis auf eine bestimmte Check_MK-Version: Ab Version 1.4.8i2 beherrscht Check_MK dies und das... Das Wort „Version“ wird nicht automatisch erzeugt. Früher was da mit <b class=new>...<b>. Diese Syntax darf jetzt nicht mehr verwendet werden.
COMMENT[Bla] Eine so markierte Stelle taucht nur im Entwicklungssystem auf und dient für unsere internen.

2.12. Anführungszeichen

Für Anführungszeichen, die ein Zitat im Text markieren (wo es also nicht um das Ascii-Zeichen „Quote“ geht, verwenden wir in der deutschen Fassung die Unicodezeichen und . Damit man die besser eintippen kann, hilft ein VIM-Makro:

~/.vimrc
" Deutsche Anführungszeichen auf und zu
imap `` „
imap `' “

Jetzt kannst du mit Backtick-Backtick das Anführungszeichen unten mit mit Backtick-Singlequote das Anführungszeichen oben tippen. In der englischen Fassung kommen normale Quotes zum Ansatz.

2.13. Screenshots und Abbildungen

Das Einbinden von Bildschirmfotos und anderen Abbildungen geschieht mit dem Makro BI:. Dies wird als eigener Absatz an den Zeilen anfang gesetzt, gefolgt vom Dateinamen. Das Bild wird in htdocs/bilder erwartet. Üblich sind PNG-Bilder. JPEG ist ebenfalls erlaubt, aber nur bei hoher Qualität, also wenn mit dem Auge keine Artefakte erkennbar sind. Gerade bei großen Screenshots sind JPEGs deutlich kleiner und daher manchmal eine sehr gute Alternative. Aber eben nur, wenn die Qualität passt.

Mehr zu Konventionen zu Screenshots weiter unten.

Ein Bild wird automatisch auf die volle Breite des Artikels skaliert, wenn das Makro ohne weitere Argumente verwendet wird:

BI:matrix_view_1.jpg

Eine Skalierung auf 60% der Textbreite lässt sich erreichen durch center width:60%.

BI:matrix_view_1.jpg center width:60%

Die Version mit Prozentangaben ist neu seit März 2019. Viele Artikel verwenden noch absolute Angaben wie width:200px oder width:200. Diese beziehen sich auf Pixel, wobei die Textbreite mit 610 angenommen wird. Bitte verwende nur noch die neue Schreibweise mit Prozentangaben.

Manchmal sieht es besser aus, wenn ein Bild links steht und vom Text umflossen wird. Das geht dann mit left - eventuell in Kombination mit einer Größenangabe. Hier ist wichtig, dass der Text dann auch lang genug ist, damit die folgenden Absätze nicht auch nach rechts verschoben werden. Außerdem sieht es doof aus, wenn unter dem Bild genau noch eine Zeile Text Platz hat.

Im Notfall darf man ausnahmsweise an den Absatz ein oder zwei <br> anzuhängen. Probier das dann bitte auch auf der Papierversion aus! Der Quellcode sieht etwa so aus:

BI:snapin_site_status.png left width:30%
Manchmal sieht es besser aus, wenn ein Bild links steht und vom Text umflossen
wird. Das geht dann mit <tt>left</tt> - eventuell in Kombination mit einer
...

Wichtige Regeln zur Skalierung von Bildern

  • Bilder sollen immer so skaliert werden, dass Schriften im Bild möglichst die gleiche Größe haben, wie die im Fließtext.
  • Auf keinen Fall darf die Schritt im Bild größer sein, als im Text! Denn das sieht so doof aus...

Hinweise zum Erstellen von Screenshots findest du weiter unten.

Hervorhebungen

Wenn du im Screenshot eine Stelle hervorheben willst (gute Idee, wenn der Text sich darauf bezieht), dann hat das BI: dafür das Schlüsselwort hilite: mit vier Zahlen. Die Zahlen sind Prozentwerte der Breite bzw. Höhe und bedeuten der Reihe nach:

  • X-Wert der Mitte der Hervorhebung
  • Y-Wert der Mitte der Hervorhebung
  • Breite der Hervorhebung
  • Höhe der Hervorhebung

Beispiel:

BI:folder_monitored_on.png center width:90% hilite:40,78,76,20

Und die Darstellung:

Die Mitte ist also bei 40%/78% der Bildgröße. Die Breite des Rahmens ist 76% vom Bild, die Höhe ist 20%. Achte immer darauf, dass das umrahmte schön in der Mitte vom Rahmen sitzt und ein hübscher Abstand da ist. Ein bisschen Spielen mit den Zahlen ist sicher nötig. Probier dabei mal bei Vim - während du auf einer Zahl stehst - die Tasten Ctrl-A und Ctrl-X.

Achtung: Wenn das Hilite in der Papierversion und in HTML nicht 100% exakt gleich sind, ist das immer ein Bug vom HTML. Das Buch ist maßgeblich. Mach deinen Artikel so, dass es im Buch passt, sag Bescheid, und wir fixen die HTML-Darstellung.

Es gibt eine kleine Hilfe, um die Koordinaten schneller herauszufinden. Ersetze BI: durch BD::

BD:folder_monitored_on.png hilite:40,78,76,20

Das sieht dann so aus:

2.14. Kommentare

Inline-Kommentare wurden schon beschrieben und werden COMMENT[so] ausgezeichnet. Das erscheint dann. Ganze Zeilen auskommentieren kann man durch drei Rauten am Zeilenanfang:

### Das hier ist alles noch nicht wirlich fertig.
### Wir sollten nach das hier beschreiben...

Während die Inlinekommentare im Entwicklungssystem noch im HTML-Code zu sehen sind, verschwinden die Zeilenkommentare komplett.

3. Erstellen von Screenshots

Beim Erstellen von Screenshots ist für ein gutes Gesamtbild des Handbuches sehr wichtig, dass diese alle auf die gleiche Art erstellt werden. Folgende Grundregeln gelten:

  • Screenshots werden grundsätzlich mit einem Browser erstellt, wo Checkboxen und Ähnliches ordentlich dargestellt und skaliert werden.
  • Auf Screenshots sind niemals Elemente vom Browser sichtbar (Locationzeile, Rollbalken und so weiter)
  • Screenshots sind für das deutsche und englische Handbuch gleich.
  • Daher werden Screenshots immer mit der englischen Spracheinstellung gemacht. Achte darauf, Chrome mit LANG= zu starten, so dass dieser mit englischen Systemtexten läuft. Das wird z. B. bei Dateiauswahldialogen relevant.
  • Screenshots werden nur auf Bildschirmen mit einer hohen Auflösung gemacht (>= 2560 Pixel)
  • Der Browserinhalt wird bis auf das maximal mögliche hochskaliert, ohne dass dabei bereits hässliche Umbrüche entstehen
  • Die Benennung der Dateien ist klein und mit Unterstrichen (keine Bindestriche)

Das Hochskalieren ist wichtig, auch wenn das Bild in der Doku dann auf „610 Pixel“ runterskaliert wird. Denn auf einem aktuellen Bildschirm wird das ja dann normal wieder hochskaliert. Ziel ist, dass selbst bei einem hochauflösenden Bildschirm der Benutzer niemals ein Bild sieht, dass schlechter als seine Bildschirmauflösung ist (also ein Pixel größer als ein Pixel dargestellt wird). Daher brauchen wir in der Auflösung eine gewisse „Reserve“.

Tipp: Es gibt für Chrome das Addon Zoomify. Mit dem kannst du den Zoom stufenlos einstellen (also in einzelnen Prozentschritten).

Achte beim Einbinden der Screenshots allerdings dann darauf, dass die normale Schrift im Screenshot nie größer ist als im Fließtext der Doku.

3.1. Namenskonventionen bei Screenshots

  • Sites heißen immer mysite, Slaves heißen immer myslave.
  • Der Benutzer heißt immer cmkadmin. Alte Screenshots mit omdadmin oder anderen Namen sollen langfristig aus dem Handbuch verschwinden.
  • Hosts in Check_MK heißen immer myserver mit einer beliebigen Zahlenfolge, wenn eine Konsolensitzung betrieben wird. In Screenshots sollte der Name das Verständnis der Thematik unterstützen.
  • Generell werden Benutzer, Passwörter, etc. als myuser, mypassword, etc. dargestellt. Sinn dahinter ist, dass immer klar ist, dass es sich hier nur um Platzhalter handelt, die vom Benutzer selbstständig durch etwas sinnvolles ersetzt werden müssen.

3.2. Screenshots von einzelnen Elementen

Dialoge, die in der GUI in Boxen daherkommen sollen wenn möglich als Einzelteile dargestellt werden. Beispiel:

Damit man das sauber einfangen kann, kann man in Check_MK alle Hintergründe auf weiß setzen mit einer nicht dokumentierten Option in multisite.mk:

etc/check_mk/multisite.mk
screenshotmode = 1

In Gimp kannst du das gewünschte Element dann zuerst grob ausschneiden und dann mit Shift-Z (Zealous Autocrop) alles Weiße außenrum automatisch wegschneiden lassen. Klappt gut, einfach ausprobieren!

3.3. Screenshots von ganzen Seiten

Möchtest du im Handbuch wirklich eine ganze Seite zeigen, weil sich das nicht gut in Einzelteile zerlegen lässt, dann mach einen Screenshot ohne Seitenleiste. Schneide dabei aus der eigentlichen Seite den Teil bis knapp über die Icons aus. Diese sollen nicht in den Screenshot.

  • Pass auf, dass die Ränder auf allen Seiten gleich groß sind - also die Breite vom blauen Hintergrund vom Rand bis zum eigentlichen Inhalt.
  • Mach es so, dass kein Browserrollbalken zu sehen ist.
  • Mach es so, dass nichts rechts abgeschnitten ist.

Hier ist ein guter Screenshot:

  • Die Ränder links, rechts und unten sind gleich groß. Der Rand oben ist - gemessen vom Check_MK-Logo aus - ebenfalls gleich groß.
  • Die Schrift ist so groß wie möglich. Der Umbruch bei Version und Core wird in Kauf genommen und stört das Layout nicht allzusehr, weil die Knöpfe bei Activate eh recht hoch sind.

Hier ein paar Beispiele von schlechten Screenshots:

  • Im Browser zu klein skaliert. Dadurch ist die Schrift sehr klein, obwohl rechts in den

Boxen noch genug Platz wäre für 1-2 Stufen größer.

  • Es wäre besser, jede der Boxen einzeln zu zeigen und zu besprechen. Eventuell diente der Screenshot nur dafür, die Childnode Generation zu zeigen. Der Rest ist Ballast.
  • Schrift viel zu klein - kaum leserlich bei der Standardbreite im Handbuch
  • Auch hier hätte wohl der Inhalt in Tree vollkommen gereicht
  • Der untere Rand ist breiter als der linke.

3.4. Erkennung der richtigen Schriftgröße in Screenshots

Damit Screenshots später in der Doku eine möglichst einheitlich Schriftgröße aufweisen, ist es nützlich das Verhältnis von Bildbreite zu Schriftgröße im Screenshot im Auge zu behalten. Maßstab ist dabei die Schriftgröße des Textes, welcher im Mittelpunkt stehen soll. In der Regel stehen Überschriften z. B. nicht im Mittelpunkt.

Gemessen wird die Höhe eines Großbuchstabens. Ideal ist z. B. E, T, F, L usw.

Leider skaliert die Schriftgröße im Bild nicht parallel mit der Schriftgröße im Text, will man die Seite im Browser vergrößern. Die folgende Tabelle stellt daher das Verhältnis bei einer Skalierung von 100% dar. Es gibt zu jeder Schriftgröße im Screenshot sowohl eine optimale Bildbreite als auch einen Bereich, der noch tolerabel ist. Alle Werte in px:

Schriftgröße im Bild Bildbreite Bereich
16 px 1200 1180 - 1220
17 px 1275 1250 - 1300
18 px 1350 1330 - 1370
19 px 1425 1400 - 1450
20 px 1500 1480 - 1520
21 px 1575 1550 - 1600
22 px 1650 1630 - 1670
23 px 1725 1700 - 1750
24 px 1800 1780 - 1820
25 px 1875 1850 - 1900
26 px 1950 1930 - 1970
27 px 2025 2000 - 2050
28 px 2100 2080 - 2120
29 px 2175 2150 - 2200
30 px 2250 2230 - 2270
31 px 2325 2300 - 2350
32 px 2400 2380 - 2420
33 px 2475 2450 - 2500

Im Idealfall stimmt das Verhältnis schon direkt beim Erstellen des Screenshots. Da die Schriftgröße bei der Bildbearbeitung nicht mehr verändert werden kann, kann man nur bei der Bildbreite nacharbeiten, z. B. in dem der Rahmen und/oder die Tabellen künstlich versetzt werden. Im schlimmsten Fall muss der Screenshot neu erstellt werden.

3.5. Screenshots von Sidebarsnapins

Da die Snapins eine feste Breite haben, können diese immer einfach gleich skaliert werden mit einer Breite von 280 Pixeln:

BI:ec_performance.png center width:280

Die Schriftgröße im Screenshot ist dann ca 10% kleiner als die Schrift im Text, was optisch meiner Ansicht hier aber besser aussieht, also eine 1:1 Skalierung:

3.6. Inhalte der Screenshots

Für die Inhalte der Screenshots gelten die Konventionen für Beispiele.

3.7. Erzeugen von Screenshots

In git/zeug_cmk/bin gibt es das Skript bildschirmfoto, dass sich hervorragend für Screenshots eignet. Am besten, du legst das mithilfe deines Windowmanagers auf eine Tastenkombination. Das Skript:

  1. Wechselt in das Verzeichnis git/mkde/htdocs/bilder
  2. Erstellt ein Bildschirmfoto vom ganzen Monitor mit einem zufälligen Dateinamen
  3. Öffnet das Bild in Gimp
  4. Löscht die Datei nach 10 Sekunden wieder

Du kannst das jetzt in Gimp bearbeiten und - wenn es was geworden ist - speichern. Das Nette: Solange du mit Gimp nichts speicherst, bleibt auch nix zurück.

4. Erstellen von Abbildungen und Diagrammen

Alle Diagramme für das Handbuch werden unter Mac OS mit dem Programm „Graffle“ erstellt. Dazu hat Mathias eine Formatvorlage für Kästen etc. erstellt. Wer ein Diagramm braucht: bitte erstmal an Mathias wenden. Das ist hier noch nicht dokumentiert.

5. Konventionen für Beispiele

5.1. Benennungen

Bei IDs, die der Benutzer frei wählen kann, ist es am besten, die Beispiel-IDs mit my beginnen zu lassen, z. B. mysite, myserver123. Durch das konsequente Durchziehen dieser Konvention ist dem Benutzer (irgendwann) klar, dass er das nicht wörtlich abtippen soll. Denn genau das ist oft das Problem: Schreibst du z. B. cmk -v HOSTNAME, werden sicher 30% der Leser das wörtlich so abtippen und nicht den eigenen Hostnamen einsetzen. Ein cmk -v myserver123 ist da viel eindeutiger!

Festlegungen für bestimmte Situationen:

  • Einzelstehene OMD-Sites heißen immer mysite. Bei Artikeln zu verteiltem Monitoring sind mymaster und myslave bzw. myslave1, myslave2 vorgesehen.
  • Beispielserver in der Überwachung beginnen mit myserver....
  • Beispielnamen, die als ID fungieren (Hostname, Contactgroup-ID), usw. sind grundsätzlich in Kleinbuchstaben.
  • Beispielnamen, die als Anzeigename fungieren, sollten Groß-/Kleinschrift verwenden und am besten Leerzeichen enthalten (z. B. My Host Group 1). So wird unterstrichen, dass dieses keine Schlüsselfunktion haben.

Bei anderen frei gewählten Namen nimm englische Ausdrücke. Das irritiert die deutschen Leser nicht. Umgekehrt wohl eher schon.

5.2. IP-Adressen

Bei deinen Tests wirst du wahrscheinlich sehr oft, die Adresse 127.0.0.1 verwenden. Nimm diese auf keinen Fall für Beispiele im Handbuch - weder in Screenshots noch woanders, es sein denn, dass dies im besprochenen Falls ausdrücklich notwendig ist. Der Benutzer wird verwirrt sein und nicht wissen, dass er die Adresse von seinem echten Slave, Host oder was auch immer angeben muss.

Um 127.0.0.1 zu vermeiden, kannst du:

  • Die externe IP-Adresse deines Testrechners nehmen (also von wlan0 bzw eth0).
  • In den Beispieldaten vor dem Screenshot oder im Text die Adresse nur für das Handbuch von Hand ändern

6. Begriffe und Sprache

Hier soll mit der Zeit etwas genauer beschrieben werden, welche Begrifflichkeit und Sprache im Handbuch verwendet werden sollen. Zwei Sachen sind schonmal klar:

  • Der Leser wird direkt und freundlich angesprochen und im Deutschen gesiezt.
  • Das Wort Schaltfläche ist strikt verboten.

7. Das Handbuch in gedruckter Form

Das neue Programm nwbook erzeugt ein PDF des Handbuchs, mit dem ein gedrucktes Exemplar des Handbuchs erzeugt werden kann. Dieses PDF darf auf keinen Fall weitergegeben werden.

Um das Handbuch zu erzeugen, ruft man im Verzeichnis git/mkde/books den Befehl ./nwbook manual.nwbook auf. Bitte verwende --help um die Optionen zu erfahren. Wichtig: du brauchst auf deinem Rechner eine vollständige Installation von LaTex. Folgende Pakete sollten genügen. Wenn nicht, ergänze bitte die Liste:

root@linux# aptitude install texlive-latex-recommended texlive-math-extra texlive-lang-german texlive-latex-extra gv texlive-pstricks texlive-generic-recommended

7.1. Bestehende Artikel für das PDF präprieren

Damit die Artikel mit nwbook sauber funktionieren, dürfen diese nicht einfach beliebiges HTML enthalten, sondern nur die oben beschriebenen Konstrukte. Bei den bestehenden Artikeln muss insbesondere Folgendes umgestellt bzw. kontrolliert werden.

<ul>, <ol> und <li>

Diese sind nicht mehr erlaubt. Es muss jetzt zwingend LI: und NL: verwendet werden.

Kaputte HTML-Tabellen

Es ist aufgefallen, dass bei vielen Tabellen im Handbuch das Tags nicht sauber balanciert sind. Es fehlen z. B. schließende <tr>. Der Parser von nwbook kann damit nicht umgehen und meldet einen Fehler. Diese Tabellen müssen repariert werden.

Spaltenbreiten in Tabellen

nwbook hat einen sehr einfachen heuristischen Ansatz, um gute Breiten von Spalten in Tabellen zu raten. Falls dies optisch nicht gut aussieht, muss man die Breite von Hand angeben. Dazu setzt man nur in der ersten Zeile in das <td> bzw. <th> Element der betroffenen Spalten das CSS-Attribut width:___% wobei man einen Prozentwert der Gesamtbreite angibt. Eine der Spalten soll man dabei ohne Angabe lassen, die 100% werden dann automatisch ausgerechnet. Beispiel:

<table>
<tr>
<td class="tt" style="width:20%">Updated</td>
<td>Eine Datei hat sich in der neuen Version geändert. Da Sie keine Änderungen
an der Datei gemacht haben, setzt Check_MK einfach die neue Defaultversion der Datei ein.</td>
</tr>

Das nwbook kann diese Format erkennen und korrekt parsen - allerdings nicht genau diesen einzigen style. Andere Angaben sind hier nicht erlaubt.

Anführungszeichen

Alle Anführungszeichen müssen wie oben beschrieben mit den speziellen Unicodezeichen gesetzt werden. Beispiel:

„Hallo Welt!“

nwbook erzeugt für Deutsch und Englisch daraus jeweils unterschiedliche passende Anführungszeichen.

7.2. Sonderfälle für die Trainings-Artikel

Die Trainingsartikel haben gleich mehrere Funktionen, welche alle zusammenhängend in der gleichen Datei gepflegt werden. Hier fließen sowohl die Überschriften ein, welche in der Online- und Buch-Version zu sehen sind, als auch die Folien für die Schulungspräsentation und Notizen für die Schulungsleiter ein. Die Elemente der einzelnen Bereiche sind jweils nur in den entsprechenden Dateien sichtbar! Daraus ergeben sich einige Sonderfälle:

Aufbau des Artikels

Jeder Tag stellt eine H1:-Überschrift dar und ist damit die oberste Ebene. Die jeweiligen Oberthemen für eine Schulungseinheit ist eine H2:-Überschrift.

Jedes Oberthema beginnt mit den Unterthemen, welche mit dem Indexmarker IN: versehen werden. Danach beginnt die Beschreibung der Unterthemen.

Jede Beschreibung fängt mit dem Dozentenmarker DO:an und bezieht sich immer nur auf eine konkrete Folie. In der ersten Zeile steht der Titel des Unterthemas. Danach können Notizen zu diesem Thema hinterlegt werden. Die Notizen werden mit einer Zeile beendet, in der sich lediglich Dozentenmarker ohne weiteren Text befindet.

Nach den Notizen werden die Folien definiert. Das können entweder Stichpunkte, welche die Erläuterungen des Dozenten ergänzen und den Teilnehmern eine Orientierung zu den Themeninhalten geben, oder eine Grafik sein.

Der erste Stichpunktmarker SI: enthält die Überschrift für die jeweilige Folie und sollte ein Unterthema spiegeln. Sollen später noch mehr Folien zu diesem Unterthema hinzugefügt werden, sollten alle Folien-Überschriften gleich sein. Alle weiteren Stichpunktmarker sind dann die Stichpunkte der Folie.

Mit dem Grafikmarker SB: können Bilder in die Folien eingebunden werden. Diese sollten ebenfalls in dem Handbuch vorkommen oder – in Ausnahmefällen – nur für die Folien erstellte Bilder sein.

Nachdem eine solche Folie abgeschlossen ist (Und sowohl Notizen, als auch Stichpunkte/ein Bild enthält), kann die nächste Folie angefangen werden. Diese beginnt wieder mit der Notizen-Überschrift für den Schulungsleiter.

Nachfolgend ein Beispiel. Der doppelte Backslash verhindert die Interpretation in diesem Artikel und wir im Original natürlich weggelassen:

training_cmk_beispiel
\\TI:Beispieltraining für die Syntax
\\
\\Hier ist ein Text, wie er in dem Artikel online und im Buch vorkommen wird.
\\
\\H1:Tag 1
\\
\\H2:Wie funktioniert der Aufbau dieses Artikels
\\
\\IN:syntax#introduction              Einführung in den Aufbau unseres Handbuchs
\\IN:syntax#special_characters        Erlaubte Sonderzeichen in den Texten
\\IN:syntax#presentation              Wie wird ein Schulungsartikel aufgebaut?
\\IN:regexes                          Wie man sich das Leben leichter macht
\\
\\DO:Einführung in den Aufbau unseres Handbuchs - Folie 1
\\DO:Hier steht Text dazu, was der Schulungsleiter so alles
\\DO:erzählen kann. Die nächste Zeile ist leer, damit in der
\\DO:Notes-Datei eindeutig ist, wo die Notizen zu einer Folie
\\DO:aufhören.
\\DO:
\\SI:Einführung in den Aufbau unseres Handbuchs
\\SI:erster Stichpunkt
\\SI:Mehr als drei Stichpunkte nur in Ausnahmefällen
\\SI:Nach dem letzten Stichpunkt eine Leerzeile
\\
\\DO:Einführung in den Aufbau unseres Handbuchs - Folie 2
\\DO:Noch mehr Text.
\\DO:
\\SI:Einführung in den Aufbau unseres Handbuchs
\\SI:Überschrift immer gleich halten
\\SI:drei Stichpunkte sind übersichtlich und ergänzen
\\SI:mehr Stichpunkte lenken eher vom Schulungsleiter ab
\\
\\DO:Erlaubte Sonderzeichen in den Texten - Folie 1
\\DO:
\\SB:eine_schoene_grafik.png

8. Workflow, Arbeit mit Jira

8.1. Arbeit mit Tickets

Erzeugen eines Tickets

Wir arbeiten nur mit drei verschiedenen Issue Types:

  1. Epic: Große Aufgabe, die fortwährend andauert (z. B. Legacy-Dokumentation loswerden). So ein Ticket beinhaltet normalerweise Subtickets.
  2. Story: Normale Aufgabe, z. B. einen Artikel schreiben. Oder etwas anderes, was eher Tage als Stunden Zeit braucht.
  3. Task: Kleine Aufgabe oder Bug, etwas, das man in kurzer Zeit erledigen kann.

Wir verwenden folgende Components:

  • Artikel
  • Buchlayout
  • HTML-Layout
  • Schulungen
  • Appliance

8.2. Übersetzung

Wenn ein Artikel bereit ist für die Übersetzung ins Englische, übergibt man das Ticket an Marcel und setzt den Status auf Ready for Translation.

8.3. Reviews

Per Default arbeiten wir bei Reviews ohne Gerrit sondern mit Kommentaren – entweder im Artikelquelltext oder mündlich (Telefon, etc.). Zwei können untereinander vereinbaren, dass sie miteinander Gerrit einsetzen wollen.

Wenn wir im Quelltext kommentieren, machen wir das mit.

Wann machen wir überhaupt Reviews?

  • Neue Artikel
  • Substanzielle inhaltliche Änderungen in bestehenden Artikeln
  • Zeugs was Anfänger gemacht haben
  • Wenn man sich selbst unsicher ist