See www.zabbix.com for the official Zabbix site.

Docs/specs/documentation

From Zabbix.org
Jump to: navigation, search

Overview

Zabbix community documentation is maintained at this wiki. Official documentation is located at https://www.zabbix.com/documentation/ with version number appended. Each version is an independent DokuWiki instance for scaling reasons.

Official documentation guidelines

Note: All of the wiki-specific notes refer to the DokuWiki instances, as set up for the Zabbix manual.

Page moving

If the location of a page or its name is not optimal, it should be moved/renamed. For this, only a special approach must be used - the "Page Move" plugin. This action can be performed only by Administrators, so one has to ask an administrator to do that.

This approach provides several benefits:

  • page changelog is preserved
  • backlinks to this page are automatically updated on all other pages

Note: to find all backlinks to current page, just append ?do=backlink to the page URL.

Content

  • Zabbix manual always documents one stable branch at a time (1.8, 2.0, 2.2 etc).
  • During branch lifetime functionality may change or be added. If so, this has to be noted. For example, a new item will have a note added "Available since Zabbix x.y.x".
    • If information about changes older than the current stable branch is available, it should not be removed. For example, 3.0 branch documentation still may contain information that some feature was added or changed in some 1.4, 1.6 or 1.8 release.
  • Links are placed in the upgrade notes to lead users who upgrade between Zabbix LTS versions only to read relevant documentation (like the upgrade notes) for non-LTS versions too.

Spelling

Note: Also see the general syntax guidelines.

English version content is created using British English.

In titles, only the first word should start with a capital letter.

Screenshots

All screenshots should be created by resizing browser so that only relevant information is visible and there's as little empty space as possible.

For screenshots, latest version of Zabbix from the corresponding branch should be used. For example, if working on 2.4 documentation, latest 2.4 version should be used. If working on trunk documentation, latest trunk version should be used. Notably, screenshots with version numbers higher than what is being documented should not be used.

Disabling anti-aliasing of screen fonts in the OS might result in smaller screenshots.

If possible, frontend version should be included in the screenshot so that it is clear how old the screenshot is. Large, unrelevant areas should not be added to the screenshot just to include the version number, though.

All screenshots are created using <browser> <version> on <os> with <desktop environment> using <window decorations>.

Window decorations and browser elements are excluded from screenshots, except where relevant.

All screenshots are kept below 600 pixels wide, keeping in mind that they should be usable for printed edition (600 pixels equals about 16cm of printed width). Exceptions are possible if it is not possible to contain useful information, but are discouraged.

All inserted screenshots are resized (using dokuwiki ?<width> syntax) to be <nn> pixels wide, so that page is not stretched in common screen resolutions.

Screenshot naming

Screenshot names should follow a scheme like this:

manpages

English manpage pages on the wiki are generated with a simple script from manpages in the distribution, not edited directly. Additional formatting of manpages is not performed, they are directly pasted with HTML embedded syntax support.

Syncing information

Information in many sections must be synchronised with code.

List of macros

Synced from ./libs/zbxserver/expression.c.

Can be obtained with:

 grep '^#define MVAR_' ./libs/zbxserver/expression.c | sed -e 's/.*\({.*}\).*/\1/' -e 's/.*"\(.*\)"/\1/'
List of trigger functions

Synced from ./libs/zbxserver/evalfunc.c.

Can be obtained with:

 grep "strcmp(function, " ./libs/zbxserver/evalfunc.c | sed 's/.*\(strcmp(function, "\)\([a-z]*\).*/\2/g' | sort -u

Conventions

Code like scripts, XML and software source, should be enclosed in <code> blocks. If supported, specific language should be added - for example, <code perl>.

Notes should be added using notes plugin functionality (see buttons above the editing area).

When linking to other sections of the manual, try to use "human readable" references, thinking of cases when people might have manual printed out.

Do not use links on words like 'here', but instead on the words that describe the target - for example, "See conference agenda." instead of "Click here to read conference agenda."

Linking with Wiki, Blog

Quality content on [Wiki] or [Weblog] should be used in the official documentation in the "See also" section. It is also possible to mention that link in several pages of documentation.

Rules:

  • stable websites should be used - that includes RFCs and Zabbix home sites (like blog, wiki). For wiki (www.zabbix.org) only simple http links should be used, i.e. *not* https;
  • external links can be used only in the "See also" section bottom of the page. In a documentation page body only an internal link can be used. Short DokuWiki's syntax of this internal link is [[#see_also|See also]] in the same page.
  • location of a wiki article has to be (re)considered and selected optimally. I.e. if a wiki article is useful enough to be mentioned in the documentation, but its location is not very good, it must be first moved to optimal location.

Examples:

  • Make sure that your system allows allocation of 36MB (or a bit more) of shared memory, otherwise the server may not start and you will see "Cannot allocate shared memory for <type of cache>." in the server log file. This may happen on FreeBSD, Solaris 8.
See the "See also" section at the bottom of this page to find out how to configure shared memory.
  • Additionally, to use any other language than English, its locale should be installed on the web server. See the "See also" section in the "User profile" page to find out how to install it if required.

Frontend references

Frontend locations are denoted as

 <first level item> -> <second level item>[ -> <third level item>]

For example, Configuration -> Actions or Configuration -> Hosts -> Items.

Individual references in the above scheme and elsewhere also should be somehow formatted (italics, like above ?).

Editing

  • Try to commit larger parts of the page, i.e. don't save small changes very often. To save the work done, use the "Preview" button.
When you click on "Preview" page is stored on the server as a draft, and you can edit it later.
During this period, other users will not see the changes already made.
If the page has a draft saved, viewing it instead of "Edit this page", "Edit Draft" button will be displayed.
Once you click "Edit Draft", make sure to choose "Recover Draft" to continue editing from the previous point.
  • Use the field "Edit summary" and mark "Minor Changes" if appropriate.
Always populate "Edit summary" field.
Remember, checking "Minor Changes" will prevent users who had subscribed to the page changes from receiving the notification.
In the revision history (accessed by "Old revisions" link on each page) such minor changes are shown in italics.
It is recommended to use "Minor Changes" option only when correcting typos.

Headings and numbering

Dokuwiki numbered headings plugin is used.

Section numbering (like in the manual) is performed manually.

To create a consistent use of heading levels, the following guidelines are proposed...

Doc Level Example in 2.0 Docs Heading Level
1 Configuration 1 (======)
2 Items 2 (=====)
3,4,... Item Types 2 (=====)
content page Zabbix agent 3 (====)

If there is an entry that does not have subpages, it will not look and sort properly in the indexmenu. A subpage with the same name should be created - it will not be shown, but will make entry look & sort properly. For example, see https://www.zabbix.com/documentation/2.2/manual/appliance/appliance


Known problems
  • Pages that are named same as the parent namespace do not appear in the indexmenu (for example, test/test). This problem sometimes can be used as feature for the correct section sorting in the Indexmenu. For instance visible Section level and invisible Subsection level. This example is a exception of general rule described in the Structure paragraph.
  • For manpage conversion to work, HTML support must be enabled, which is supposedly a security risk (XSS etc). These wiki instances are not editable for the general public, so the risk should be small.

See also (example described above)

  1. to configure shared memory for Zabbix daemons