Paint-by-numbers

[Ethan Galstad]

I might as well through my 2 cents into this little discussion.  Here 
goes...

To say that the Nagios docs are among the worst out there for open 
source network apps probably isn't true.  Check out other monitoring 
apps on SourceForge and have a look at their documentation sometime.  
To say that it sucks for new users is probably very true though. 
Nagios has a high learning curve.

I wrote about 95% of the current documentation and hated every second 
of it.  In fact, the only thing I hate more than reading 
documentation is writing it.  Writing 1-2-3 "paint by numbers" 
documentation would be nice for new users to have (if they read it), 
but I can't really be the one to do it.  I'm so far removed from 
knowing what a newbie's perspective is that it wouldn't do me much 
good to try anyway.  Developers don't usually write docs for end 
users because they (a) are too close to the product and (b) probably 
lack basic "grammir skillz" brought on by caffeine overdose and sleep 
deprivation.  Both apply to me.

If the documentation is lacking, people need to step up and 
contribute.  That's how things get done.  In this case, people who 
have just reached the "aha" stage of the learning curve should be 
writing the docs for newbies.  Something to think about if you just 
got Nagios up and running...  

BTW, I do think "A Paint-By-Numbers Guide To Installing Nagios" is a 
great title for new documentation. :-)



On 15 Oct 2002 at 13:51, Carroll, Jim P [Contractor] wrote:

> My first comment is one of administrivia.  Please do not change the Subject,
> as it breaks software which organizes mailing lists by subject thread.
> 
> > >You also say that Nagios is poorly documented (for) "the 
> > common user)."
> > >Maybe I'm missing something, but Nagios appears (to me) to 
> > be targetted for
> > >installation by an experienced UNIX/Linux systems 
> > administrator, not the
> > >common user.
> > 
> > But you have to admit, even the experienced admin guy 
> > scratches his head
> > over it
> > from time to time. 
> 
> I scratch my head because I'm doing "what if" scenarios in my head.  And you
> know what the solution to this is?  Just do it.
> 
> > >One of the problems of the "paint-by-numbers" approach is 
> > that everyone
> > ends
> > >up with the same picture.  Want sample config files?  
> > They're there.  Want
> > >more examples/suggestions?  That's what this mailing list is for.
> > 
> > Paint-by-number for common tasks is a big "time saver". I for 
> > one don't want
> > to be working 60hr weeks cause it is taking me hours and hours to get
> > something "simple" configured that if I had a basic "blue 
> > print" would have
> > cut the time by 1/2. 
> 
> 1. The "blue print" here is called "documentation".  It exists.  And it
> works.
> 
> 2. If you're working 60hr weeks to get a basic configuration of Nagios to
> work, perhaps you're in over your head.  Even half of that, 30 hours, is far
> too much time to be spending on something as a rudimentary configuration of
> Nagios.
> 
> > If the paint-by-numbers method is not good, then all the user manuals
> > written over the past 30+yrs are incorrect and should be scrapped. :)
> 
> I've yet to see a paint-by-numbers manual in my 14 years as a UNIX systems
> administrator.  You must be thinking about a book on how to paint by
> numbers.
> 
> > This list is fantastic. Without this list, it would be almost 
> > impossible for
> > new Nagios users to get the product up and running in a 
> > somewhat timely
> > fashion. 
> 
> New Nagios users?  Or new to UNIX/Linux systems administration?  An
> executive in a company doesn't need to know the first thing about the
> Bourne/bash shell, but equipped with a web browser on a functional (and
> properly configured) computer, this executive could login to Nagios and
> browse.
> 
> > >Looking for help configuring Apache?  That's not really what 
> > Nagios or this
> > >mailing list is about, but you might find someone willing to help you
> > there.
> > 
> > Would be great to have a "top 10" problems U might encounter 
> > installing
> > nagios with Apache. I would consider this almost a must. without a web
> > server Nagios is worthless. It shouldn't be a 700 page repeat 
> > of apache
> > docs, but a happy medium
> 
> Hint:  http://www.apache.org/
> 
> > >Looking for help configuring Sendmail so you can get your 
> > notifications?
> > >Again, that's not really what Nagios/this mailing list is 
> > about, but you
> > >might find someone (like myself) willing to help out.
> > 
> > Again, having a "top 10" problems or providing a basic config 
> > as part of the
> > docs or a supplemental doc would be a great time saver. 
> > Sendmail is probably
> > used by 70%+ of users to send out notifications
> 
> Don't get me started on Sendmail.  Or DNS/BIND.  Or how to build a firewall.
> These are all subjects which take a modest amount of effort to understand
> and configure properly.  If given a boilerplate example based on a number of
> assumptions, it will invariably lead the majority of newbies to "it didn't
> work/it broke/etc".  Then you're back into the loop of "what's your
> configuration, what are you trying to do, etc."  Many times a person will
> say what they're trying to accomplish at the micro level, while trying to
> obscure what they're trying to accomplish in the big picture.  (I know,
> because I've caught myself doing this very thing.)  In the final analysis,
> these examples that I suspect you're looking for will lead you to believe
> that it can only be done the one way.  I urge you to go back and *slowly*
> read over the documentation.  (I say this, because I know I'm the impatient
> type, when it comes to getting something as powerful as Nagios up and
> running; I tend to skim lightly over what the salient points appear to be,
> and if it doesn't work, drill down a bit at a time.  Patience is a virtue.)
> 
> As someone else has suggested, if you're not happy with the current
> documentation, you're more than welcome to write up your own and either
> offer it here, or ask Ethan to host it on his site.
> 
> > >Nagios is vast, of that there is no doubt.  If you feel 
> > you're qualified to
> > >do the installation, then by all means, hang in there; 
> > frustration is a
> > sign
> > >that success is just around the corner.  :)
> > 
> > You are correct, the amount of info supplied with Nagios is vast. But
> > without more paint-by-numbers examples, new users to the 
> > product don't know
> > what to ask for or how to ask it. They become frustrated and 
> > "give up".
> 
> It sounds as if you have some statistics (of newcomers to Nagios) to back up
> your claim.  Please share with the list.
> 
> jc
> 
> 
> -------------------------------------------------------
> This sf.net email is sponsored by:ThinkGeek
> Welcome to geek heaven.
> http://thinkgeek.com/sf
> _______________________________________________
> Nagios-users mailing list
> Nagios-users at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/nagios-users
> 



Ethan Galstad,
Nagios Developer
---
Email: nagios at nagios.org
Website: http://www.nagios.org



-------------------------------------------------------
This sf.net email is sponsored by: viaVerio will pay you up to
$1,000 for every account that you consolidate with us.
http://ad.doubleclick.net/clk;4749864;7604308;v?
http://www.viaverio.com/consolidator/osdn.cfm