[Linux-HA] Anouncing The Heartbeat Education Project
Sander van Vugt
mail at sandervanvugt.nl
Thu Jul 5 04:38:34 MDT 2007
> I think the idea of gathering (tested!) example configurations, which
> are kept uptodate with the code changes as well, is a great plan, and we
> clearly have too few of those yet. In particular, we need more "building
> blocks" to combine - "this is how you do shared storage", "this is how
> you do apache", "this is how to do drbd", "this is how to combine them",
> "this is stonith".
Agreed, this is the first part that we can take care of, and we can do
this fast. Most interesting piece here is how we are going to get it on
the website. I am not *at all* an expert in how to organize these
things, but we should make sure that everyone can benefit from it in an
organized way. If someone could help me getting started in creating the
website content I'm willing to take care of that.
> My main concern is that this new effort is not disjunct from the
> existing ones; for example the one started by Novell here:
> or the information already in the wiki.
I think they should be complementary. Let's start with this "building
blocks" page and once we have that, let's continue by creating *the*
documentation portal page that links to all the other information in an
organized way. I think we can do that in a structured and well-organized
> The most important aspect we have is to build up a structure into which
> people can insert more information easily. The Wiki is great for the
> second part, but needs leadership for the first (right now, it's an
> unstructured mess); and then there's some "boring" work to be done to
> review and integrate the existing bits into the new structure.
Would it be an idea to create this portal page (phase 2 of the project)
that just links to all the information that can be found on the Wiki?
IMHO this portal page should be the responsability of a few, not of many
like the wiki, just to make sure that structure and overview is
maintained. In the ideal world, thse few would get an update message
once information has been added to the Wiki (can that be automated?), so
that the portal page can be updated. Unfortunately, this - I'm affraid -
- is going to be manual work.
> I think the Novell provided documentation, which is based on docbook
> xml, is probably the way to go for the reference documentation and the
> more stable building blocks. Manpages et cetera can be automatically be
> generated from that source. (I can put you in contact with our
> documentation folks if you want to.) We want this documentation to be
> open, free, and complete.
> (They can also help with language review etc.)
It seems like an excellent idea to get the Novell documentation folks
involved with this. I think we can mutually benefit from eachothers
> I think the Wiki is a great place to complement such a structure; it can
> annotate improvements, host information which is still in-flux because
> the code is still evolving too quickly, and collect bits which haven't
> yet made it into the "reference". And, of course, to collect references
> to relevant documentation which might be hosted elsewhere, presentations
> et cetera.
To be honest, the Wiki is more or less a disorganized place by nature.
I'm afraid we loose sight on the structure if we do it from there. What
would you think of this "portal page" on www.linux-ha.org/Education?
That way we can separate the dynamic part from the static part.
> Then, there's one more task which needs to be considered - maintenance.
> Developers are great, but we have this frustrating tendency to forget to
> update the documentation when we change code. ;-) It'd be great if
> someone would step forward to monitor the checkins for possible
> documentation impact.
I can't estimate how much time this would take. In the ideal world, it
would be a community effort. In the not-so-ideal world, I could invest
some time in that (if the developers wouldn't expect me to scrutinize
the source code in order to detect possible changes). I can see a nice
cooperation here between the developers and the Education Project
> And, if the documentation examples could be "regression tested" so they
> always work.
Agreed, but again, that might involve a lot of work. What if for example
we put in version numbers of HB versions where the examples have been
created on? Seems like a decent start to me, that involves a lot less
Thanks for your support,
More information about the Linux-HA