Hi Henrik
A documentation project would serve multiple purposes.
By documenting something, you reinforce your own knowledge of what you document. (Something a few of us could use)
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.)
It makes it easy for anybody - even junior sys-admins to implement Hobbit
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.
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.
Basic FAQ (Anybody can contribute to this, just by providing the Q)
Setting up your own tests (How-to)
Creating custom graphs (How-to)
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.
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.
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.
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
- 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 :-)
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.
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.