Paint-by-numbers

[Carroll, Jim P [Contractor]]

You've brought up a couple of excellent points which I'd like to address.

1. Writing docs is often a thankless task.  I know I've tried my hand at it,
and tried to 'remove' myself far enough to ask myself what a newbie to the
things I've had my hands all over would want to know.  The deeper you get
into the technology, the harder it is to recall everything that you wanted
to put in the docs.

2. Spelling/grammar boo-boos.  It's been a while since I've scoured the
Nagios docs, but I do recall finding a couple mistakes here and there.
Assuming I find them, what's the best process for me to submit corrections?

Honestly, the Nagios documentation is one thing which *really* impressed me.
The impressive features had a little bit to do with it, too.  ;)

jc

> -----Original Message-----
> From: Ethan Galstad [mailto:nagios at nagios.org]
> Sent: Tuesday, October 15, 2002 11:59 PM
> To: nagios-users
> Subject: Re: [Nagios-users] RE: Paint-by-numbers
> 
> 
> 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
> _______________________________________________
> Nagios-users mailing list
> Nagios-users at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/nagios-users
> 


-------------------------------------------------------
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