[hobbit] hobbit documentation and packaging projects

[Vernon Everett]

Hi Henrik

A documentation project would serve multiple purposes.
1. By documenting something, you reinforce your own knowledge of what
you 
   document. (Something a few of us could use)
2. If it is used, it would leave you with more time for interesting
stuff
   like coding :) which will give you time to create an even better
product
   instead of wasting time answering e-mails from people like myself who

   didn't bother to RTFM properly. (See quotes below.)
3. It makes it easy for anybody - even junior sys-admins to implement
Hobbit
4. By making things really easy, you increase adoption. I have abandoned

   many tools in the past simply because they are too poorly documented
to
   be easily implemented. This will increase your user-base.
5. Right now, a mailing list and e-mail is easy to manage. But how many 
   sites out there run Hobbit? What happens to your coding time when
that 
   doubles? Triples? Increases tenfold? 

Don't get me wrong, I love the cosy feeling you get from a mailing list.
I also love ribbing the Microsoft guys in the office when I get e-mail
from the author of the product giving me assistance. I always tell them
"Let's see you do that with Micro$oft". :-) But like any other open
source product out there, to really grow, it needs better docs.
Where would Linux be if it weren't for those handy How-to docs?

Nobody is expecting you (Henrik) to do all the documentation. There are
plenty of us out there who have sufficient knowledge to contribute to a
documentation project, and even more who would benefit from it.

Documentation projects I see as being really useful.
1. Basic FAQ (Anybody can contribute to this, just by providing the Q)
2. Setting up your own tests (How-to)
3. Creating custom graphs (How-to)
4. Simple setup guide. Most users would be sys-admins, so we don't need
much 
   help there , but we all have areas of speciality and ignorance. As an

   example, I struggled to get the web pages right, but only I have
never 
   set up a web server before.
5. A detailed trouble-shooting guide. (Something most products don't
have)
   Most products have a good how-to, but nothing detailing what to do if

   something doesn't work, or goes wrong.
6. A list of bb scripts "converted" to work on hobbit. If you had to
modify 
   any bb scripts from deadcat to work correctly with Hobbit, what did
you 
   do, and why.
7. There's probably a hell of a lot more, but I have only had 2 double 
   espressos this morning, so I am still struggling to think properly.
(Time 
   for another 2)

A number of these can be explained by doing an RTFM on man pages for
Hobbit, LARRD, rrdtool etc. etc. and then trying to tie the knowledge
together.
However it would be a lot easier and more efficient to create a new doc,
detailing just the bits of each that we need to run Hobbit effectively

Cheers
    V

Motivational quotes for this project :-)

People do not cooperate under the division of labour because they love
or should love one another. They cooperate because this best serves
their own interests. Neither love nor charity nor any other sympathetic
sentiments but rightly understood selfishness is what originally
impelled man to adjust himself to the requirements of society, to
respect the rights and freedoms of his fellow men and to substitute
peaceful collaboration for enmity and conflict.
- Ludwig von Mises

It is not from the benevolence of the butcher, the brewer, or the baker,
that we expect our dinner, but from their regard to their own interest. 
- Adam Smith



-----Original Message-----
From: Henrik Stoerner [mailto:henrik at hswn.dk] 
Sent: Wednesday, 25 May 2005 4:38 AM
To: hobbit at hswn.dk
Subject: Re: [hobbit] hobbit documentation and packaging projects

On Tue, May 24, 2005 at 10:47:44AM -0500, T.J. Yang wrote:

> Following items that need to be done and I am willing to help on
> 
> 1. Digitalize the hobbit compilation and packaging  process for
different 
> Unixen.
>    So we don't need keep answering how to compile hobbit on ???
platform 
> issues.

I may be biased, but I don't think there's been that many "silly"
questions about how to build Hobbit. Most of the cases that have been
real issues have been due to my failure to write truly portable code,
and they have been dealt with by fixing the code.

The few things that have been truly platform-specific - like the HP-UX
compiler bug that was brought up yesterday - is something that should
be documented.

Building "shrink-wrap" packages of Hobbit is something that I do for my
personal use (it's just the easiest way to install it on many systems).
And for the not-quite-so-experienced admin out there I think they are
really useful to get something up and running quickly and get off to a
good start with using Hobbit, instead of struggling for a couple of days
with the fine details of configure, make etc.  So there are Linux based 
packages in deb- and rpm-format. I know there are NetBSD packages of 
Hobbit available, and I wouldn't be surprised if someone was working on 
putting it into the FreeBSD "ports" collection.  But I also think that 
most of the die-hard sysadmins here actually prefer to build from source
:-)


> 2. Set up a hobbit wiki page/book  (on mediawiki ?)
>    I like mediawiki because there is a command line client in perl to
>   automate the wikipage update.
>
> 3. Prepare the hobbit document in docbook format ?
>    The docbook format is the final resting place of hobbit wiki.
>    So we can generate pdf and rtf  easily.

I know there was/is a Wiki for BB. If you feel it would be useful for
Hobbit, go ahead - it's not a format I use very much. Probably just 
me being old-fashioned - e-mail and newsgroups are my preferred
communication methods.

> Seriouslly, please follow up this thead to let me know your comment.
> Should I spend the efforts on these tasks ? Are you willing to help
etc...

I really appreciate your willingness to undertake some work on Hobbit,
especially with documentation which most programmers really try to
avoid. I do write documentation, but I may be an exception - it's simply
because when the documentation exists, I get more time to do the
interesting stuff (code) since I don't have to spend so much time
answering questions.

But before you embark on this, ask yourself: What problem will I solve
by doing this ? Setting up a Wiki is fine - but only if it gets used.
For that to happen, there must be stuff there that people want to read.
So what's missing today - is it the "beginners guide to monitoring your
network" ? Or a "How to monitor your datacenter and survive" guide ?
Or maybe a "Building graphs for your Boss" description?

I guess, what I'm trying to say is that you should narrow your focus
- at least to begin with. Then, when you have something going, you can
broaden the scope.


Henrik


To unsubscribe from the hobbit list, send an e-mail to
hobbit-unsubscribe at hswn.dk


_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

NOTICE: This message and any attachments are confidential and may contain copyright material 
of Australian Finance Group Limited or a third party. It is intended solely for the purpose of the 
addressee and any other named recipient. If you are not the intended recipient, any use, 
distribution, disclosure or copying of this message is strictly prohibited. The confidentiality attached
to this message is not waived or lost by reason of the mistaken transmission or delivery to any 
unintended party. If you have received this message in error, please notify the author immediately or 
contact Australian Finance Group on +61 8 9420 7888.