[hobbit] hobbit documentation and packaging projects

[Henrik Stoerner]

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