Articles, which are completely new, should always be written on the state of the future version of Checkmk. If the content is also relevant for an already published version, the article can be ported to the respective branch afterwards. This article may then need to be adapted and rewritten to be correct for that version.
As soon as a first version of an article is ready and at least the basic structure is in place, an article can basically already be published in the respective branch.
There are two phases that an article can have during initial writing:
| draft |
The article is started and already has first (helpful) content. However, it is not yet finished or corrected. Content may be missing or incomplete, or the article may not have been proofread yet. The article is marked accordingly with 'draft' in the revision date. |
| final |
The article is finished, has been proofread and checked for completeness/correctness and typos. The article can be marked with a date in revision date. The date of completion applies, not the date when the commit entered git. |
You know it: You have finished an article about a component and already after 2 days it is either not complete or even wrong. So after writing is before writing. If you revise an existing article, the writing is ideally done quickly. Here it is only necessary to follow the general instructions.
The same principles apply when revising an article as when writing a new one. When the revision starts, the article changes to draft state and stays there until the review is completed and all comments are incorporated.
For minor changes, it is not always necessary to go through the complete process chain including review and transfer for translation, e.g. correcting typos / wording, changes to formatting, renaming of (image) files, etc.
Either the change only affects one language variant (e.g. typos) or it involves small corrections / additions that can be quickly corrected in both languages.
To track the translation status, we use the git history. To do this, we use certain keywords in the git commit messages to make tracking easier. You only need to use these keywords if you want to include a statement about the translation relevance of the commit.
Once there are content changes in a language that need to be translated, you don’t need to pay attention to anything else in the commit message. These commits are automatically captured when checking which ones have not been translated yet.
In certain cases, however, no translation is necessary at all because they are only editorial changes (typos, wording changed). For these changes there are the keywords only-de and only-en, which exclude a change from the check:
user@host:~$ git commit de/my_article -m "only-de: typo fixed"Once an article is ready, a copy is pushed to the other language. For this there is the keyword content-sync:
user@host:~$ git commit en/my_new_article.asciidoc -m "content-sync: wrote new helpful article"The keyword marks the time when an article is fully content-synced in all languages. Important: The content is in sync, but not necessarily already translated!
So with these keywords we have the clear advantage that on the one hand we can’t go wrong with changes in the first place and on the other hand we have the possibility to make small changes without generating too many false positives.
The attentive reader will have noticed that not all conceivable cases are covered. To keep the effort as low as possible for everyone involved, you are welcome to translate minor content changes directly. This way the articles in the different languages do not diverge too much and on the other hand it saves the staff of tribe29 a lot of time and work. It is then important to commit the changes from both language versions of an article in the same commit:
user@host:~$ git commit en/my_article en/my_article -m "added example for ..."Not all features of Asciidoctor are currently used in the documentation of Checkmk. To facilitate/enable a homogeneous picture, here is a (non-exhaustive) list of functionalities and how they should be used:
Each article uses a basic set of metadata and header lines that are required when converting to HTML. Here is a table of header lines and whether they are mandatory or optional:
| Attribute | Description | Mandatory? |
|---|---|---|
include::global_attr.adoc[] |
Imports predefined attributes that can be used in the text and sets basic attributes like the path to images and icons. |
Yes |
= Title |
The title of the article as it will appear at the top of the article on the page and also as it should be displayed in the table of contents of the User Guide. Ideally, the title should not exceed 30 characters. |
Yes |
:revdate: |
The date of the last content change in the format yyyy-mm-dd. Articles that are still in draft or review will have the word 'draft' instead of the date. |
Yes |
:title: |
The HTML Meta Title is displayed in the browser window or browser tab as the title. It should be identical to the title of the article, if necessary extended by an addition, which then serves the search engine optimization (SEO). Optimal length is between 50 and maximum 70 characters. |
Yes |
:description: |
Short description of what the article is about, in a length of between 120 and a maximum of 160 characters. |
Yes |
{related-start} & {related-end} |
Links to other articles, which are helpful for understanding or extend the context. |
No |
So a document header could look like this:
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}
Headings are used at a maximum of four levels and are designated Level 0 through Level 3 according to the AsciiDoc naming convention:
== The title of the article (Level 0) == A chapter heading (Level 1) === A section heading (Level 2) ==== A section heading (Level 2)
| Markup | Explanation |
|---|---|
_text_ |
The font style italic is used for the introduction of terms and for mild emphasis. |
*text* |
The font weight bold is used when there is a clear emphasis. Please use very sparingly. |
`omd config` |
Monospaced font for file names, directory names, path names, commands, user names (e.g. from console sessions) and GUI input, in short: everywhere where an exact match is important. |
[.guihint]#Add host#] |
Quotes a text from the Checkmk user interface. This is currently shown in italics. |
Enumerations can occur unordered (with bullets) or ordered (numbered). Lists exist only at one level, i.e. lists are not nested:
* Point one * Point two . At first do A . After that do B
In addition, so-called "description lists" can be used. These can be very handy when a handful of terms need to be explained or introduced in the form of a list:
Keyword:: Here comes a description for this keyword.
Tables can be distinguished in different ways in AsciiDoc. To have a common picture, tables are built based on the following syntax:
[cols=3] (1) |=== |Column 1 |Column 2 |Column 3 (2) |Line 1.1 |Line 1.2 |Line 1.3 (3) |One more line|| |===
(1) Here the number of columns is specified. Syntactically not necessary, but it simplifies reading.
(2) Title of the columns in the table
(3) Each row gets its own line and each column starts with a | (Pipe)
As an alternative, the column width can also be specified as a percentage. The ~ (tilde) serves here as a marker that you do not want to specify a fixed width for this column:
[cols="10,~,~,20"] (1)
(1) This table would thus have four columns, where the first would have a width of 10% and the last would have 20%. The width of the two middle columns will be calculated automatically.
[cols="10,~,~,20",options="header"]
The additional optional attribute options="header" turns the 1st table row into a table header and the texts of this row into bold.
Images (graphics, screenshots, icons) are used together for German and English, i.e. if images contain text, then in English.
All images should contain an alt text.
Only images in PNG format may be included.
An image is automatically scaled to full width if the macro image:: is used without further arguments.
Image files are included in the source file as follows:
image::filename.png[alt="Here is the alt text"]
Console sessions - i.e. dialogs on the terminal and only these - are marked with the {shell} or {shell-raw} macros.
The actual block with the contents of the session is opened and also closed with a quadruple hyphen (----).
Console sessions are not included as screenshots!
As such they would not be well modifiable and besides, the reader would not be able to copy anything out.
Especially for input prompts on the shell there are a few important macros that should be used:
| Wanted input prompt | Macro | Output |
|---|---|---|
root user |
|
|
normal Linux user |
|
|
OMD user |
|
|
OMD user on central instance |
|
|
OMD user on remote instance 1 |
|
|
OMD user on remote instance 2 |
|
|
Example in source code:
[{shell}] (1)
----
{c-user} cat /etc/hosts (2)
127.0.0.1 localhost localhost.local
----
(1) This attribute sets the main options for the command line while also allowing formatting, attributes, and macros.
If only attributes are to be allowed, {shell-raw} can also be used.
(2) Here is an example of an input prompt to simulate a shell.
For things like omd status output, there is an option to make letters colored.
All the colors of the rainbow can be used by specifying the appropriate keyword in square brackets.
The text to be colored must then be placed between two double crosses:
[{shell}]
----
[red]#This text will be red in HTML#
----
The display of file contents works almost the same as that of a console session.
There is only a different macro called {file} for this.
Which attributes this macro contains can be checked in the file global_attr.adoc.
In addition, the name and path of the file to be displayed must be specified after a simple dot before the macro.
Paths within an OMD site are always specified as relative paths:
.~/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
----