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 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.
I think you should do things the Open Source way and open up editing of the documentation to a trusted set of users. I don’t think this trusted set should be by invitation either, I think it should be something which is merit based such as 200+ forum posts. If a user has been around long enough to answer that many posts it’s a pretty good chance they actually care about Zabbix.
Maintaining the walled garden can be useful but it does not scale as quickly or as efficiently as doing things in an Open Source manner. I also think there are many other benefits to this, the biggest of which is members of the community would feel like they have a greater impact in helping the Zabbix project. Over the years many people have wanted to help make the documentation better but haven’t been able to. The current ability to comment is an improvement but it still is a hindrance to someone who feels that a paragraph or sentence needs a tweak.
Empower your users to play a greater role in making Zabbix awesome!
oh, just for the record, discussion on manual access moved on to the zabbix forum at http://www.zabbix.com/forum/showthread.php?t=19740
Good to see the manual is getting attention, god knows there’s room for improvement 🙂
Checked out the proposed outline and it seems fine to me, I couldn’t spot anything I’d necessarily miss or change.
I do agree that a section on recommended usage for some scenario’s would be nice. Maybe small, medium and large scale deployments and what the recommendations are for each?
what would those recommendations include ? maybe you can provide some short example on what they could look like ?
Hi,
i also think that zabbix documentation lacks detail-depth in many aspects.
(In my case monitoring with snmp)
I really think that it would a good idea to allow registered users to improve the documentation. I think that zabbix user community is capable to add documentation for undocumented features, to enhance documentation with sucessful usage scenarios
and to improve the documentation didactically.
Maybe you can implement a review process by using a staging-wiki or by using/enhancing docuwiki functionality.
I would be your first author/editor.
Regards
Marc
thanks for the offer. maybe you can chime in on the forum thread for that purpose as well ? -> http://www.zabbix.com/forum/showthread.php?p=74482
I think that the documentation really needs a quick “getting started guide / Best practices”, that would show a basic setup. For instance :
– Define your hosts
– Use groups to “nest” your hosts
– Define templates (items, triggers, graphs)
– Link your host to different templates
– Define your alarms, based on trigger criticity and host group
The manual currently explains each of those concepts, but I think that a newbie will have to read all the manual only to have an idea on how to set up a new Zabbix environment that will be easy to update in the next years (i.e. : using templates, groups, etc.)
that’s a good point – there is currently a quickstart guide, but it stops at creating a single item, trigger and being able to send out notifications. so for the next version it could be expanded to include hostgroups, templates etc
Please start by fixing the structure of the documentation and linking between sections, only then worry about adding more content.
For example, I just spent 15 minutes trying to find documentation about Maps. I could see the word “maps” mentioned in many places, but none linked to anything that tells me how to use them (in particular I want to know how to duplicate items on a map and how to autofill all the items on a map from an existing groups and trigger dependencies).
Try something like this:
Concepts
– items
– triggers
– hosts
– etc
– bringing it all together: a nice picture of how hosts relate to items, then to triggers, actions, etc, etc (that was the single biggest stumbling block to learning Zabbix for us, other than the crappy web UI)
Configuration
– the detailed howto for each page which you can link to directly from the relevant pages in the webUI. For example, one page on what all the options in host configuration mean (I still don’t know what the right side does).
Examples
– how to monitor a web server
– how to monitor mysql
etc
“Please start by fixing the structure of the documentation”
ahh, that’s exactly what this initiative is about – figuring out what and where should be in the manual.
Great discussion – I am so glad that you are taking the documentation seriously.
DokuWiki is fine, however it lacks a good export format for printing. ODF does the job, but lacks Contents and Index out of the box. LyX/LaTeX export would be so great to have.
Also, the documentation about Zabbix agent behaviour and keys is far from enterprise-ready documentation. It can be very tricky to figure out specific behaviour of Zabbix in a critical application monitoring. Happy to help here 🙂 Maybe some kind of approval document system in place would do the trick.