Rebooting Zabbix Manual

fake_first_name_5 fake_last_name_5

October 26, 2010

Zabbix manual can be both source of joy and frustration. While some areas are easy enough to find and documented in detail, some are a bit lacking. Improvement has to start somewhere, so here’s an attempt at “rebooting” Zabbix manual. Tools used First, the technical part. Zabbix manual for version 1.8 uses online system, based […]

Tools used

First, the technical part. Zabbix manual for version 1.8 uses online system, based on DokuWiki. While this choice has some problems, it has been decided that for 2.0 documentation current system will be kept, because investigating and implementing a different one would be too time intensive at this point. So this means that Zabbix 2.0 manual will have to be drafted with these limitations in mind.

Proposed structure

Next, content. Although before content proper structure should be devised. So here’s initial proposal of the new Zabbix manual structure/outline as a plaintext file. It keeps manual and API documentation as two separate sections, and then everything else goes below manual. Tab indentation denotes subsections.

Proposed Zabbix 2.0 manual outline

A few issues with this outline:

“Events” inside configuration section is not really configuration related, but it fits nicely between triggers and actions. Maybe should be moved elsewhere.
Right after configuration section, there are some smaller entries. Some of these don’t fully fit in configuration part as well – these might have to be moved elsewhere.
Some things have not been included from previous version as separate items yet – for example, “Goals and Principles of Zabbix” (could be added either in “about”, or folded into “what is zabbix”) and “performance” (advice about performance would be very generic and possibly outdated soon, so it’s usefulness could be doubtful).

It is also possible that some important things are missing – if so, come and tell what exactly and where it should be added.

DokuWiki limitations

Additionally, there are some problems, seen with DokuWiki and its plugins, used for Zabbix manual. These can impact the structure of the manual, and any help in easily resolving them would be appreciated.

Sidebar expandable menu does not work in some browsers (for example, Opera 10.11)

Syntax error while loading: line 2 of inline script at
 http://www.zabbix.com/documentation/ :
Expected statement
<![CDATA[//><!--
----------^

Page numbering in sidebar is inconsistent – for example, notice numbering of “Configuration” subsections – some are prefixed with “4”, some are not. Possibly affected by the order these pages are accessed in and put into cache.

Only 5 levels of numbered headings are available, which impacts the amount of detailed structurisation a document like Zabbix manual may have – for example, “Configuration” part already has exceeded that limit in the proposed outline.

Pages with subpages in the indexmenu plugin tree are displayed as directories, and they are displayed before individual pages. As such, in this proposed structure “Manual Structure & Concepts” (which would not have subpages) would come after “about”, which would be undesirable.

ODT export plugin template feature does not work. Well, it does not work as expected – if template is used, all heading styles are lost. If it is not used, heading styles are preserved.

If you have any feedback on the proposed manual outline or any other aspect of Zabbix manual, pop in channel #zabbix on Freenode IRC network, or join the forum thread for this purpose – or maybe just leave your comment on this blog entry.

fake_first_name_5 fake_last_name_5