Rebooting Zabbix manual

[richlv]

so... there's this idea floating around that zabbix manual should be improved. and one way to start it could be with coming up with a new structure. see blog post here : http://blog.zabbix.com/rebooting-zabbix-manual

if you have any feedback, feel free to discuss here or join #zabbix irc channel on freenode

[nelsonab]

I Commented on the blog but I feel it may get more needed discussion here. I think overall the layout is fine, but I think things should be done more in an Open Source manner. By this I mean, open up the documentation so that members of the community can directly edit it. Until Zabbix has a formal process to allow people to register to help develop Zabbix you might use the number of forum posts a person makes. I feel a merit based system like this would be the most evenly fair for everyone. In the blog post I said 200+ as these users have shown their commitment to Zabbix, but the community may feel otherwise and this is good to discuss.

Bottom line Open Source methodologies can scale much better than a walled garden approach. Yes we can comment now and that is good, but we also can't make a structural change or add a section to the documentation based on a forum post where someone was confused about something in the documentation.

Bottom line, empower the Zabbix community to make Zabbix more awesome!

[Zaniwoop]

I agree.

Contributers should at be least forum "Senior Members".

[MrKen]

I've noticed on some sites that they have an Official Manual, and also a User-maintained Manual.

An administrator (richlv) could monitor changes to the User-maintained Manual and update the Official manual if the changes are deemed acceptable.

MrKen

[richlv]

I've noticed on some sites that they have an Official Manual, and also a User-maintained Manual.

well, that would be a role wiki could have filled before, but there didn't seem to be that much activity (except some quite decent howtos that have appeared there).

An administrator (richlv) could monitor changes to the User-maintained Manual and update the Official manual if the changes are deemed acceptable.
MrKen

in addition to a low level of interest in such a community-maintained documentation an approach like this would result in lots of duplicated efforts, as i'd expect content to even out and become very similar, if not identical over time

now, opening access to more people interested in improving the official manual might be the way forward. of course, the issue there often is that it requires decent knowledge about zabbix, decent english and an ability to explain things to other people - all of which i can't claim to possess myself =)

[fmrapid]

I have the impression there are at least 4-5 people that comme to mind that would have great input in updating the documentation. As long as there is revision control and approvals.
This is clearly a winning solution. Those that wish could also review suggestions for documentation improvements and integrate them.

For all others documentation improvements should be published to the forums and/or the tracker.

Cheers,

fmrapid

[scoopex]

Community Documnetation

Hi,
i 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 successful usage/best practice scenarios and to improve the documentation didactically.

Maybe it is possible to implement a review process by using a staging-wiki or by using/enhancing docuwiki functionality.

I would be glad to add documentation to zabbix.

Regards
Marc

[zalex_ua]

So.
I am pleased that here I can speak publicly (just forgive me for my english and see the attached file on the original Russian (UTF8) ).
I feel that I have some impetus to the emergence of this article. I have long implore the author to update some plugins, etc.

I want to know - is planned to create a new tree of documentation, or update existing records? Describe in a few words as you can see the migration to the new structure. It seems to me to create a new structure, and the old left available for reading.
Describe what levels will make numbered. It is necessary to know how to solve some problems with plug-ins.


So I can thoroughly analyze the aspect of multi-language documentation.

Definitely not enough of section FAQ. A few questions directly for him.
- Zabbiks server is running - NO,
- Host name of the interface must match the hostname parameter in the configuration file of the agent,
- Others.

Folder should contain only plugin Include, otherwise users might miss important pages.
Now this plan does not meet here this page: http://www.zabbix.com/documentation/1.8/protocols
or this one http://www.zabbix.com/documentation/...nual/processes (Only just saw this page!)


According to the structure - very correctly that the page "items" will be divided into separate pages.
For the section "log" do add a subsection "syslog" and point out here is the link http://www.zabbix.com/forum/showthread.php?t=19180
I note that I have to finish their similar but slightly different solution, and one day publish it on the wiki.

I suggest the section "user macros" to separate from the section "macros" and placed after the section "triggers". This should be noticeable to users under investigation Items and Triggers. And in the "macros" to refer to "user macros".

Very good, it would be "appendixes" and there will be separate tables for "items" and "macros". I did this not once thought.

I suggest "frontend sections" changed to "frontend menu".

For other languages - you need to create a Glossary (I understand "concepts -> definitions" just fits)
I have long thought to do. There will be a list of the basic concepts of translation interface
For example:
Item -
Action -
Application -
Media -

I hope the table will be altered as there http://www.zabbix.com/wiki/playgroun...em_table_style

About the icons using the interface - they can be dynamic, ie, lead to different pages manul, including multilingual interface language for those who are well translated (only Russian and Japanese), it will accelerate the translation and improvement of other languages. This may be a configurable option in the user profile. It will be very useful for beginners.

I totally agree with Nelsonlab - but automatically give users direct access to the English documentation - it is dangerous. Better yet on a request or suggestion from the developers and only proven fighters. It should be taken as agreement and the rules, so that for the translators on other languages, these constant changes did not become a nightmare.
In this connection it is useful to read my thoughts about translation http://www.zabbix.com/wiki/contrib/translations

I have long ago registered the request.

https://support.zabbix.com/browse/ZBXNEXT-459

That is what I suggest is a compromise between the proposal Nelsonab and MrKen. This idea needs to be developed.

If there was some sort of a system change (page creation) by the user and the approval of the developers, but I do not know that. Each sentence in the documentation should be a thoughtful, balanced. And I agree with Richlv that the documentation should not be too detailed. Better develop the site wiki.

The technical part
Dokuwiki is quite popular engine for the documentation of Open Source projects, and we got used to it. This is a plus.
I have not once heard the idea to move to Mediawiki, but I'm not sure whether it could be better. There's much harder to edit the table http://www.mediawiki.org/wiki/Help:Tables although there maybe much more.
For example http://www.net-snmp.org/wiki/index.php/Main_Page I do not like navigation. Very difficult for me out there to find the desired page.
At one time I found myself dokuviki only to understand the plugins and improve the Zabbix documentation system. Honestly.
With the plug-in with time I think we can figure out and fix the problem. Just yesterday there were some new ideas.

I want to draw attention to the multilingual aspects.
At one time when I studied Zabbix - I read the first Russian documentation page, I was a little obscene language that is not all clear, and then read the same page but in the English for would understand the true. In fairness I will say that the initial translation (a tremendous job) did DotNeft him for that, despite the errors, we need to say a big thank you.
This became the impetus for my desire to fix documentation and GUI translation. And I did it.
Note that I'm Ukrainian and usually speak Ukrainian, but knowing the great Russian, I improve its translation.


What does this mean?
Bad translation pushes from his reading, and it discredits the idea of multi-lingual.
Need to strongly encourage translators to do translations with high quality and do so without making it hard. And frequent changes in the documentation - it's hard for translators. Look for other languages - they do not significantly match actual content of English documents. Some pages (especially Portuguese) are simply copied from the English and already are outdated. In this regard, it must be some order. Important aspects in this regard are set out in my article on the wiki link above.

Please remember this when choosing a new ideology of community users write access and order changes.

If changes to the documentation will be made often - this will be a nightmare for translators. The authors of the changes should accumulate ideas and then do a comprehensive addition to the documentation.
Maybe do some intermediate name space in which users will publish a new page, the developers will check to make edits and then copy in the original namespace?
It will be convenient and users and developers and translators. I now think that it will be better way !!!

I wrote this a few days, constantly looking up on other aspects (Richlv knows what ), and I think that not all the ideas presented. To be continued ...

[zalex_ua]

Requested to install additional plug-ins, they are useful to administer (for translators and others):
http://www.dokuwiki.org/plugin:changes - very necessary!
http://www.dokuwiki.org/plugin:usersubscriptions - very necessary!
http://www.dokuwiki.org/plugin:comment - will be useful. Compatible with ODT Export.

I see that the Pagelist plugin already installed, and it is very good, it is useful for Changes plug-in.

I ask to create a closed namespace for those who will have the write documentation permissions. It does not need to see regular users, because there will be work time information and garbage. Maybe it's just right for my proposal for the commit from community and the amendments by developers.

There are editors, translators and developers can create pages that will be used the possibility of mentioned plug-ins. I already tested it on my own Wiki and I understand that I can currently do not have enough.

[zalex_ua]

I think that the sections 'configuration' and 'administration' need to move up one level and split them to separate pages.
Now these two pages is too large, and search necessary information in them is very difficult.

[richlv]

I want to know - is planned to create a new tree of documentation, or update existing records? Describe in a few words as you can see the migration to the new structure.

the idea for 2.0 docs is to create new documentation tree from the scratch, copying over up-to-date content and modifying/adding missing/outdated one.

Describe what levels will make numbered. It is necessary to know how to solve some problems with plug-ins.

oh, numbering... it is a significant problem. personally i have no idea how to best solve it. any suggestions that don't involve manually managing numbering or trick the caching system are more than welcome

Definitely not enough of section FAQ. A few questions directly for him.
- Zabbiks server is running - NO,
- Host name of the interface must match the hostname parameter in the configuration file of the agent,
- Others.

i think that's what the "troubleshooting" section in the proposed structure would be great for

Folder should contain only plugin Include, otherwise users might miss important pages.
Now this plan does not meet here this page: http://www.zabbix.com/documentation/1.8/protocols
or this one http://www.zabbix.com/documentation/...nual/processes (Only just saw this page!)

good point - could be observed while creating 2.0 docs

For the section "log" do add a subsection "syslog" and point out here is the link http://www.zabbix.com/forum/showthread.php?t=19180

i believe manual should only be concerned with official functionality. it's enough of a task to keep it up to date, adding docs on external projects that might become unmaintained later would be too burdensome...

I suggest the section "user macros" to separate from the section "macros" and placed after the section "triggers". This should be noticeable to users under investigation Items and Triggers. And in the "macros" to refer to "user macros".

maybe just link in relevant sections of item & trigger pages to user macros and macros ? would keep the manual more structured

I suggest "frontend sections" changed to "frontend menu".

hmm. but it doesn't concern just the menu, that part is supposed to contain detailed (hopefully ) descriptions of all pages in those sections...

For other languages - you need to create a Glossary (I understand "concepts -> definitions" just fits)

yes, exactly - and not just for other languages
item/trigger/event aren't immediately obvious, and there are many more terms in use around zabbix

I hope the table will be altered as there http://www.zabbix.com/wiki/playgroun...em_table_style

will have to sort out & fully test that odt export problem, and yes, that would be much easier to read

About the icons using the interface - they can be dynamic, ie, lead to different pages manul, including multilingual interface language for those who are well translated (only Russian and Japanese), it will accelerate the translation and improvement of other languages. This may be a configurable option in the user profile. It will be very useful for beginners.

not sure what this means - could you please rephrase it ?

I totally agree with Nelsonlab - but automatically give users direct access to the English documentation - it is dangerous. Better yet on a request or suggestion from the developers and only proven fighters.

agreed - besides, i don't expect a huge amount of quality documentation writers to rush doing just that, most likely we will have a few people who will deal with typos and other quick tasks

In this connection it is useful to read my thoughts about translation http://www.zabbix.com/wiki/contrib/translations

hehe, yeah, these should be slightly more polished & agreed upon (as well as merged with a few i had somewhere in a file some time ago...) - will make life easier for all contributors

https://support.zabbix.com/browse/ZBXNEXT-459

That is what I suggest is a compromise between the proposal Nelsonab and MrKen. This idea needs to be developed.

interesting idea. i think it might even work to some extent. a problem might arise from outdated and unmaintained articles on the wiki still being linked in from the manual. although they could easily be unlinked at any time. i think i like this idea in general

If there was some sort of a system change (page creation) by the user and the approval of the developers, but I do not know that.

sounds complicated. i'd hope we all are sensible persons and can discuss and work as a team without convoluted technical processes - at least for a while

And I agree with Richlv that the documentation should not be too detailed. Better develop the site wiki.

hey ! i did not say that =)
docs can never be too detailed ! (they can just be badly structured with details thrown in the middle of a high level overview).
now 3rd party mods, addons and other things... yeah, i wouldn't say that belongs in an official manual of some project.

I have not once heard the idea to move to Mediawiki, but I'm not sure whether it could be better. There's much harder to edit the table http://www.mediawiki.org/wiki/Help:Tables although there maybe much more.

i once saw somewhere a quite nice visual table editor plugin for mw, but i can't find it anymore. maybe it was on wikia, maybe somewhere else... although at the time when i tried it it was not released yet. the demo page had something about wildlife - frogs, maybe ? if anybody knows what this is about, please, share a link to it

For example http://www.net-snmp.org/wiki/index.php/Main_Page I do not like navigation. Very difficult for me out there to find the desired page.

i think that's site dependent. i'm sure it is possible to create nicely navigable documentation in mw as well. but - that's something to consider long term, it's clear that for 2.0 we're staying with the same technical base & solution.

Bad translation pushes from his reading, and it discredits the idea of multi-lingual.
Need to strongly encourage translators to do translations with high quality and do so without making it hard. And frequent changes in the documentation - it's hard for translators. Look for other languages - they do not significantly match actual content of English documents. Some pages (especially Portuguese) are simply copied from the English and already are outdated. In this regard, it must be some order. Important aspects in this regard are set out in my article on the wiki link above.

some translations are indeed... not up to the level
maybe new translations should be hidden from general public by default until authors consider them to be ready. what to do with updates is another topic again.

If changes to the documentation will be made often - this will be a nightmare for translators. The authors of the changes should accumulate ideas and then do a comprehensive addition to the documentation.

on the other hand, piling changes up will lead to conflicts and more... piled up work later. i don't think extremism in either direction is good, so maybe just trying to be sensible here will work long term. again, discussing all these things amongst documentation contributors every now and then should helpalot. there's a reason why irc is used by absolute majority of opensource projects

Maybe do some intermediate name space in which users will publish a new page, the developers will check to make edits and then copy in the original namespace?
It will be convenient and users and developers and translators.

but it results in a bottleneck at devs. and delayed reaction to those pages will discourage contributors. i'd like to try simpler approach first

I think that the sections 'configuration' and 'administration' need to move up one level and split them to separate pages.
Now these two pages is too large, and search necessary information in them is very difficult.

hmm. is this about the new proposed structure ? in there config part is already significantly split up, and admin part is only in the frontend section area, which all are further expected to be split up per subsections.

[richlv]

...getting back to the structure of the manual. there were very few suggestions, and several of them have been applied. so, unless somebody has some nice idea, i guess we can go on with that structure

one thing i don't like in particular is that "configuration" part, which includes non-config things, like events, using graphs and other things. maybe it should be renamed to "using zabbix" or something else, leaving substructure as is...

any ideas ?

[zalex_ua]

EXTRA-MEGA-SUPER-PUPER quoting. continuation

oh, numbering... it is a significant problem. personally i have no idea how to best solve it. any suggestions that don't involve manually managing numbering or trick the caching system are more than welcome

Yes. I am almost sure that this is an unsolvable problem. I described it as a note here. If, however, manual control of cache will be accepted, then the problem can be solved.

First way (trick the caching system):
you can make scheduled operation with two steps:
1. delete all *.i and *.xhtml files from ./cache directory and all subdirectories. I've already explored this behavior (plugin Cache/Revisions Eraser helped me).
2. immediately wget http://www.zabbix.com/documentation/1.8/complete
As result cache will be builded right way.
Schedule this script every 24hours.

Other way:
at folder level we just need to write a number. Like "===== 4. Configuration =====" without using Numbering plugin future. Of course, disadvantage of this way - inferior article will not inherit the chapter number in its structure.

i believe manual should only be concerned with official functionality. it's enough of a task to keep it up to date, adding docs on external projects that might become unmaintained later would be too burdensome...

I understand you, and do not want to argue, but tell me how users can easily find such a wonderful solution? I think we can do an article on the wiki with all the sources and make reference to this article. Needed to support such great ideas from community. At the forum, there are numerous examples where users are unaware of existing similar solutions.

maybe just link in relevant sections of item & trigger pages to user macros and macros ? would keep the manual more structured

agree !

hmm. but it doesn't concern just the menu, that part is supposed to contain detailed (hopefully ) descriptions of all pages in those sections...

ok.

yes, exactly - and not just for other languages
item/trigger/event aren't immediately obvious, and there are many more terms in use around zabbix

ok. other language documentation will also contain the original values (English) of concepts. Something like Элементы данных = Items, etc...

will have to sort out & fully test that odt export problem, and yes, that would be much easier to read

why we are still not done? ODT plug-in has long been fixed, you only need to update it on your site! no problems with export already. I'm waiting for you decision which style tables will be better and I'm ready to remake all the required tables.

not sure what this means - could you please rephrase it ?

oh-oh, my English. see picture attachment. Multilingual documentation can be supported - this may be a configurable option in the user profile. All this will be very useful for beginners.

https://support.zabbix.com/browse/ZBXNEXT-459 interesting idea. i think it might even work to some extent. a problem might arise from outdated and unmaintained articles on the wiki still being linked in from the manual. although they could easily be unlinked at any time. i think i like this idea in general

All wiki resources should contain the version validation info. Very easy example - i simply added a note. Something easy rules should be introduced.

hey ! i did not say that =)
docs can never be too detailed ! (they can just be badly structured with details thrown in the middle of a high level overview)

I remember a time when you're telling me this - I remember it well. Unfortunately I can not find where you are to me is saying. But let's not argue. The thought was that official manual should not be overly detailed. No problem - you right ! Sorry.

some translations are indeed... not up to the level
maybe new translations should be hidden from general public by default until authors consider them to be ready. what to do with updates is another topic again.

IMHO - is bad idea to hide new translations from general public by default until authors consider them to be ready. I'm sure that in this case it did not appear ever - the translator does not have the patience to do the job, the interim result of which no one sees. Better show it and encourage others to connect to the translation work, following my described rules, and everything will be okay.
And definitely a long time ago it was time to update the Translation plugin. I've already talked about this a thousand times. Already tired of repeating. ; )

on the other hand, piling changes up will lead to conflicts and more...

I mean if contributor have an idea to append a new text, change the existing one, then he should read the whole article and add, change all his wishes, and only then once save the article. It's better than changing two words every day after each reading. Somewhere around that.
I already have extensive experience translating changing articles (and even check someone else's translation), and I must say if one day you will save some article 5 times - it's worse than you would have done it once. Believe me. Some compromises are permissible if the change is significant and voluminous.
And always ! the author should write comments to the changes. Even for minor changes.

hmm. is this about the new proposed structure ? in there config part is already significantly split up, and admin part is only in the frontend section area, which all are further expected to be split up per subsections.

I mean "frontend section" area if compared with the current 1.8 structure. I understand what you mean - everything should be fine.

one thing i don't like in particular is that "configuration" part, which includes non-config things, like events, using graphs and other things. maybe it should be renamed to "using zabbix" or something else, leaving substructure as is...

any ideas ?

Yes, of course, I also had this feeling.
"events" did not place in the "configuration" section. I propose move it to "frontend sections" - "monitoring"



And and at the end. No response to my inquiry
Especially the first plug-in, and preferably also the second.
I ask again to create a closed namespace for those who will have the write documentation permissions.
You will understand later why I ask, really. To me it's hard to explain in words.

p.s. I hurt, I can not write more than 4 smilies (pictures).

[richlv]

Yes. I am almost sure that this is an unsolvable problem. I described it as a note here. If, however, manual control of cache will be accepted, then the problem can be solved.

seems to be pretty unsolvable indeed. well, i guess let's work on 2.0 docs for a while and see...

I understand you, and do not want to argue, but tell me how users can easily find such a wonderful solution? I think we can do an article on the wiki with all the sources and make reference to this article. Needed to support such great ideas from community. At the forum, there are numerous examples where users are unaware of existing similar solutions.

i think your suggestion below for having sort of "see also" sections might work nicely. if somebody maintains the docs in the wiki, wonderful. if users complain that they are unmaintained, "see also" link goes away until wikidocs are updated.

ok. other language documentation will also contain the original values (English) of concepts. Something like Элементы данных = Items, etc...

yep, i guess that will have to be detailed in translator/documentation guidelines

why we are still not done? ODT plug-in has long been fixed, you only need to update it on your site! no problems with export already.

because it was not released for quite some time afterwards
but yeah, let's see what can be done about that.

oh-oh, my English. see picture attachment. Multilingual documentation can be supported - this may be a configurable option in the user profile. All this will be very useful for beginners.

ah, that - definitely, that idea has been floated around for a long time. well, "definitely" being that i fully agree to and support such an idea, not that it will appear soon...

I remember a time when you're telling me this - I remember it well. Unfortunately I can not find where you are to me is saying. But let's not argue. The thought was that official manual should not be overly detailed.

maybe the idea was that some pages shouldn't go into extremely deep details - but those could always be documented in appendixes, tech docs or other sections

Yes, of course, I also had this feeling.
"events" did not place in the "configuration" section. I propose move it to "frontend sections" - "monitoring"

but it's not just some frontend section... it's all about events - concept, generation etc.

i agree with other things you listed, and the plugin upgrades are on the todo list

p.s. I hurt, I can not write more than 4 smilies (pictures).

HA. death to the emo-icons =)

[richlv]

...and one more question regarding the manual structure. where should faq section go ?

my current idea is - an appendix that is linked to from the intro and troubleshooting sections (troubleshooting != faq)