Artikel, welche komplett neu geschrieben werden, sollten immer auf dem Stand der zukünftigen Version von Checkmk geschrieben werden. Falls die Inhalte auch für eine bereits veröffentlichte Version relevant ist, kann der Artikel danach entsprechend in den jeweiligen Branch portiert werden. Eventuell muss dieser Artikel dann angepasst und umgeschrieben werden, damit er für die jeweilige Version korrekt ist.
Sobald eine erste Version eines Artikels fertig ist und mindestens die Grundstruktur steht, kann ein Artikel grundsätzlich auch bereits in den jeweiligen Branch veröffentlicht werden.
Dabei gibt es zwei Phasen, die ein Artikel beim initialen Schreiben haben kann:
| draft |
Der Artikel ist begonnen und hat bereits erste (hilfreiche) Inhalte.
Er ist aber noch nicht fertig oder korrigiert.
Es können Inhalte fehlen oder unvollständig sein oder der Artikel ist noch nicht korrekturgelesen worden.
Der Artikel wird entsprechend mit |
| final |
Der Artikel ist fertig, wurde gegengelesen und auf Vollständigkeit/Korrektheit und Tippfehler geprüft. Der Artikel kann mit einem Datum in Aktualisierungsdatum versehen werden. Es gilt das Datum der Fertigstellung, nicht das, an dem der Commit ins git kam. |
Man kennt es: Man hat einen Artikel zu einer Komponente fertiggestellt und schon nach 2 Tagen ist er entweder nicht mehr vollständig oder gar falsch. Nach dem Schreiben ist also vor dem Schreiben. Wenn man einen bestehenden Artikel überarbeitet, ist das Schreiben im Idealfall schnell getan. Hier gilt es nur die allgemeinen Hinweise zu beachten.
Auch bei der Überarbeitung eines Artikels gelten die gleichen Grundsätze wie bei der Neuerstellung. Mit dem Beginn der Überarbeitung wechselt der Artikel in den Draft-Zustand und bleibt dort so lange, bis das Review abgeschlossen ist und alle Kommentare eingearbeitet sind.
Bei kleineren Änderungen muss nicht immer die komplette Prozesskette inklusive Review und Übergabe zur Übersetzung durchlaufen werden, z.B. bei Korrektur von Tippfehlern / Formulierungen, Änderungen an Formatierungen, Umbenennen von (Bild)-Dateien, etc.
Entweder betrifft die Änderung nur eine Sprachvariante (z.B. Typos) oder es handelt sich um kleine Korrekturen / Ergänzungen, die schnell in beiden Sprachen korrigiert werden können.
Um den Übersetzungsstatus zu verfolgen, benutzen wir die git Historie. Dazu werden bestimmte Schlagwörter in den git Commit-Nachrichten benutzt, um die Verfolgung zu vereinfachen. Diese Schlagwörter musst Du nur dann verwenden, wenn Du eine Aussage über die Übersetzungsrelevanz des Commits mitgeben willst.
Sobald es inhaltliche Änderungen in einer Sprache gibt, die zu übersetzen sind, musst Du bei der Commit-Nachricht nichts weiter beachten. Diese Commits werden automatisch erfasst, wenn geprüft wird, welche noch nicht übersetzt wurden.
In bestimmten Fällen ist aber gar keine Übersetzung nötig, weil es nur redaktionelle Änderungen sind (Tippfehler, Formulierung geändert). Für diese Änderungen gibt es die Schlagwörter only-de und only-en, die eine Änderung von der Prüfung ausschließen:
user@host:~$ git commit de/my_article -m "only-de: fixed typo"Sobald ein Artikel fertig ist, wird eine Kopie in die andere Sprache geschoben. Dafür gibt es das Schlagwort content-sync:
user@host:~$ git commit en/my_new_article.asciidoc -m "content-sync: wrote new helpful article"Das Stichwort markiert den Zeitpunkt, an dem ein Artikel in allen Sprachen inhaltlich vollständig synchron ist. Wichtig: Die Inhalte sind zwar synchron, aber nicht zwingend bereits übersetzt!
Mit diesen Stichwörtern haben wir also den klaren Vorteil, dass wir zum einen bei Änderungen erst einmal nichts falsch machen können und zum anderen die Möglichkeit haben, kleine Änderungen zu machen, ohne zu viele False-Positive-Meldungen zu erzeugen.
Der aufmerksame Leser wird gemerkt haben, dass nicht alle denkbaren Fälle abgedeckt sind. Um den Aufwand für alle Beteiligten so niedrig wie möglich zu halten, kann man kleinere inhaltliche Änderungen auch gerne direkt übersetzen. Auf diese Weise gehen die Artikel in den unterschiedlichen Sprachen nicht zu weit auseinander und zum anderen erspart es den Mitarbeitern von tribe29 viel Zeit und Arbeit. Wichtig ist es dann, die Änderungen von beiden Sprachversionen eines Artikels in denselben Commit zu übergeben:
user@host:~$ git commit de/my_article en/my_article -m "added example for ..."In der Dokumentation von Checkmk werden derzeit nicht alle Features von Asciidoctor verwendet. Um ein homogenes Bild zu erleichtern/ermöglichen, gibt es hier eine (nicht erschöpfende) Liste an Funktionalitäten und wie sie verwendet werden sollten:
Jeder Artikel verwendet ein Grundgerüst an Metadaten und Kopfzeilen, die bei der Konvertierung zu HTML benötigt werden. Hier eine Tabelle an Kopfzeilen und ob diese verpflichtend oder optional sind:
| Attribut | Beschreibung | Verpflichtend? |
|---|---|---|
include::global_attr.adoc[] |
Importiert vordefinierte Attribute, die im Text verwendet werden können und setzt grundlegende Attribute, wie den Pfad zu den Bildern und Icons. |
Ja |
= Titel |
Der Titel des Artikels, so wie er am Anfang des Artikels auf der Seite erscheint und auch im Inhaltsverzeichnis des Handbuchs angezeigt werden soll. Idealerweise sollte der Titel die 30 Zeichen nicht überschreiten. |
Ja |
:revdate: |
Das Datum der letzten inhaltlichen Änderung im Format yyyy-mm-dd. Artikel, die noch im Entstehen oder im Review sind, erhalten anstelle des Datums das Wort |
Ja |
:title: |
Der HTML Meta Title wird im Browser-Fenster bzw. Browser-Tab als Titel angezeigt. Er soll identisch zum Titel des Artikels sein, ggf. erweitert um einen Zusatz, der dann der Suchmaschinenoptimierung (search engine optimization, SEO) dient. Optimale Länge liegt zwischen 50 bis maximal 70 Zeichen. |
Ja |
:description: |
Kurzbeschreibung, worum es in dem Artikel geht, in einer Länge von zwischen 120 und maximal 160 Zeichen. |
Ja |
{related-start} & {related-end} |
Links zu anderen Artikeln, die hilfreich für das Verständnis sind, oder den Kontext erweitern. |
Nein |
So eine Kopfzeile eines Dokuments könnte also so aussehen:
include::global_attr.adoc[]
= My article about feature X
:title: My article about feature X
:description: Learn how to set up feature X and use it efficiently in {CMK} to get the most out of your monitoring environment.
{related-start}
link:dashboards.html[Dashboards]
link:basics_downtimes.html[Scheduled downtimes]
{related-end}
Überschriften werden auf maximal vier Ebenen genutzt und nach der AsciiDoc Namensgebung mit Level 0 bis Level 3 bezeichnet:
== The title of the article (Level 0) == A chapter heading (Level 1) === A section heading (Level 2) ==== A section heading (Level 2)
| Auszeichnung | Erklärung |
|---|---|
_text_ |
Die Schriftlage kursiv wird verwendet bei der Einführung von Begriffen und bei einer milden Hervorhebung. |
*text* |
Die Schriftstärke fett wird bei einer deutlichen Hervorhebung verwendet. Bitte sehr sparsam verwenden. |
`omd config` |
Diktengleiche Schrift (monospaced font) für Dateinamen, Verzeichnisnamen, Pfadnamen, Befehlen, Benutzernamen (bspw. aus Konsolensitzungen) und Eingaben in der GUI, kurz: überall dort, wo eine exakte Übereinstimmung wichtig ist. |
[.guihint]#Add host#] |
Zitat eines Textes aus der Checkmk}-Benutzeroberfläche. Dies wird aktuell kursiv dargestellt. |
Aufzählungen können ungeordnet (mit Bullets) oder geordnet (nummeriert) vorkommen. Listen gibt nur auf einer Ebene, d.h. Listen werden nicht verschachtelt:
* Point one * Point two . At first do A . After that do B
Außerdem können noch sogenannte „Description Lists“ verwendet werden. Diese können sehr praktisch sein, wenn eine Hand voll von Begriffen erklärt oder in Form einer Liste eingeführt werden sollen:
Keyword:: Here comes a description for this keyword.
Tabellen können in AsciiDoc unterschiedlich ausgezeichnet werden. Um ein gemeinsames Bild zu haben, werden Tabellen basierend auf folgender Syntax aufgebaut:
[cols=3] (1) |=== |Column 1 |Column 2 |Column 3 (2) |Line 1.1 |Line 1.2 |Line 1.3 (3) |One more line|| |===
(1) Hier wird die Anzahl der Spalten angegeben. Syntaktisch nicht notwendig, aber es vereinfacht das Lesen.
(2) Titel der Spalten in der Tabelle
(3) Jede Zeile bekommt eine eigene Zeile und jede Spalte beginnt mit einem | (Pipe)
Als Alternative kann auch die Spaltenbreite in Prozent angegeben werden. Die ~ (Tilde) dient hier als Marker, dass man für diese Spalte keine feste Breite angeben möchte:
[cols="10,~,~,20"] (1)
(1) Diese Tabelle würde demnach vier Spalten haben, bei denen die erste eine Breite von 10% haben und die letzte 20% haben würde. Die Breite der beiden mittleren Spalten wird demnach automatisch berechnet.
[cols="10,~,~,20",options="header"]
Durch das zusätzliche optionale Attribut options="header" wird die 1. Tabellenzeile zur Tabellenüberschrift und die Texte dieser Zeile fett ausgezeichnet.
Bilder (Grafiken, Screenshots, Icons) werden gemeinsam für Deutsch und Englisch genutzt, d.h. enthalten Bilder Texte, dann in Englisch.
Alle Bilder sollen einen Alt-Text enthalten.
Es dürfen ausschließlich Bilder im Format PNG eingebunden werden.
Ein Bild wird automatisch auf die volle Breite skaliert, wenn das Makro image:: ohne weitere Argumente verwendet wird.
Bilddateien werden wie folgt in die Quelldatei eingebaut:
image::filename.png[alt="Here is the alt text"]
Konsolensitzungen - also Dialoge auf dem Terminal und nur diese - werden mit den Makros {shell} bzw. {shell-raw} ausgezeichnet.
Der eigentliche Block mit dem Inhalt der Sitzung wird mit vierfachem Bindestrich (----) eröffnet und auch wieder geschlossen.
Konsolensitzungen werden nicht als Screenshots eingebunden!
Als solche wären sie nicht gut änderbar und außerdem könnte der Leser dann nichts herauskopieren.
Speziell für Eingabeprompts auf der Shell gibt es dafür ein paar wichtige Makros, die unbedingt verwendet werden sollen:
| gewünschtes Eingabeprompt | Makro | Ausgabe |
|---|---|---|
root-Benutzer |
|
|
normaler Linuxbenutzer |
|
|
OMD-Benutzer |
|
|
OMD-Benutzer auf Zentralinstanz |
|
|
OMD-Benutzer auf Remote-Instanz 1 |
|
|
OMD-Benutzer auf Remote-Instanz 2 |
|
|
Beispiel im Quelltext:
[{shell}] (1)
----
{c-user} cat /etc/hosts (2)
127.0.0.1 localhost localhost.local
----
(1) Mit diesem Attribut werden die wichtigsten Optionen für die Kommandozeile gesetzt und gleichzeitig auch Formatierungen, Attribute und Makros erlaubt.
Sollen nur Attribute erlaubt sein, so kann man auch {shell-raw} nutzen.
(2) Hier ist ein Beispiel eines Eingabeprompts, um eine Shell zu simulieren.
Für Dinge wie die Ausgabe von omd status gibt es die Möglichkeit, Buchstaben farbig zu machen.
Alle Farben des Regenbogens können durch die Angabe des entsprechenden Schlüsselworts in eckigen Klammern verwendet werden.
Der einzufärbende Text muss dann zwischen zwei Doppelkreuzen stehen:
[{shell}]
----
[red]#This text will be red in HTML#
----
Die Darstellung von Dateiinhalten funktioniert fast genauso, wie die einer Konsolensitzung.
Es gibt dafür nur ein anderes Makro namens {file}.
Welche Attribute dieses Marko konkret enthält, kann bei Interesse in der Datei global_attr.adoc geprüft werden.
Zusätzlich muss vor dem Makro noch der Name und Pfad der darzustellenden Datei hinter einem einfachen Punkt angegeben werden.
Pfade innerhalb einer OMD-Instanz werden immer als relative Pfade angegeben:
.~/var/log/cmc.log
[{file}]
----
2016-02-24 16:30:48 [5] Successfully initiated connection to Carbon/Graphite
2016-02-24 16:32:57 [4] Connection to Carbon/Graphite at 10.0.0.5:2003 failed
2016-02-24 16:32:57 [5] Closing connection to Carbon/Graphite
----