[CentOS-docs] Contribution to wiki: nagios incompatibility with centos 5.2

Thu Sep 17 17:57:40 UTC 2009
Max Hetrick <maxhetrick at verizon.net>

Marcus Moeller wrote:

> So I am a bit disappointed (but can understand) ppl. like Max who
> already contributed high quality docs in the past are re-signing from
> contributing to the wiki (just because one or two other guys have a
> different pov). I have also suggested that docs like the CentOS
> specific owlriver rpm howtos  (http://www.owlriver.com/tips/non-root/)
> could as well resist on the CentOS wiki. But it's not my decision.


The problem is to me, and the reason I decided I don't want to 
contribute any longer, is the fact that you have CentOS team members not 
agreeing on a format for content. You have one or two saying they want 
it this way, and you have some saying it should be this way.

You have one team member stating they believe writers should go upstream 
for all documentation purposes, and then another saying no. The problem 
with that is the fact that it's not realistic to take that approach, 
because not all projects are going to be willing to fix their 
documentation upstream. That's the reason why I write things that I 
write. To make it easier on admins and users to get the application 
going, and then if they want to further learn, tackle more complex 
documentation. That's the exact reason the Nagios guide exists in the 
first place. When I started working with it, I had trouble learning it. 
I decided to make that experience better for others and write a howto.

To go off-topic, as a side job, I write publications with this exact 
approach and get paid for it. My articles there are exactly that, called 
TechTips. I take a piece of software, or a topic, and write a technical 
tip meant to get the reader/user up and running. Part of my success 
there has been because I take a how-to approach to the guides, which the 
readers love. From there, they can expand their horizons with 
documentation all they want for more complex issues. Obviously there is 
a need for such articles, because they pay me and tell me as such. :) 
They're in the business of documentation and articles, so they should 
know. Most people always want a more simple way of understanding a 
concept, rather than diving into code documentation, or this case, 
Nagios' cryptic and overwhelming docs.

To continue about the wiki, the problem for contributors like myself 
then becomes, well what do I do, or how should I write for them. 
Although I often times enjoy the democracy of opinions on the docs list, 
it becomes confusing for a contributor when you have team members 
disagreeing in public forum. One time a topic of post is ok'd to be put 
on, the next time then it's criticized and not ok. There is no 
consistency for authors and contributors, and I really believe that 
needs worked out within.

What really needs to occur is that the team members really need to agree 
on, and publish on the site, some standards that ALL the team members 
can agree on. At that level, all of these issues could be ironed out, to 
hopefully create a set of standards of acceptable content. Then these 
types of conversations and arguments won't need to occur, or in theory 
shouldn't need to occur.

Perhaps I'm dreaming here to think that everyone on the team can do so, 
but I think something like that needs to happen one way or the other, 
because eventually, no one is going to want to post on the wiki for 
these reasons.

Perhaps I'm out of line here, and perhaps I'm going on and on in a 
diatribe, but this is my opinion on the matter, and my further detailed 
reasons for not wanting the headache of contributing any longer.

Regards,
Max