Hi Lars, > 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: > http://www.novell.com/documentation/beta/sles10/heartbeat/data/heartbeat.html > 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 way. > > 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 actions. > > 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 people. > > 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 effort. Thanks for your support, Sander _______________________________________________ Linux-HA mailing list [email protected] http://lists.linux-ha.org/mailman/listinfo/linux-ha See also: http://linux-ha.org/ReportingProblems
