Wiki -> Docbook integration for the handbook

[Scott Balneaves]

Hello all,

So, after a discussion last night, we have some ideas regarding the handbook,
the wiki, and how to tie the two together.

We have 3 goals with the handbook (in no particular order)

1) Try to make it as simple as possible to contribute to, so that average users
   who are looking to help out with Edubuntu can make a contribution.
2) Clean up the wiki to make it a useful resource.
3) Have a source of offline, translatable docs for users with limited/no
   internet access.

To this end, the following suggestion has emerged:

1) Create a wiki instance, with a separate name from the regular wiki.  The
   goal of the regular wiki is to provide topic based help, as opposed to the
   handbook, which is a more "cover to cover" read.  Several names have been
   suggested, including knowledgebase.edubuntu.org, handbook.edubuntu.org, and
   LaserJockandsbalneavsexcellentdocadventure.edubuntu.org.  The idea with this
   is to provide the necessary "separation" from the regular topic based help.
   We'd have to liase with CIS to make this happen.
2) We'd initially load the wiki instance with current handbook information.
   General topic areas we'd like to see:
   a) Edubuntu-specific documentation (what is it, installing stuff, etc.)
   b) guide to using Education apps (specifically, how to
      use them in education)
   c) classroom management
   And others as they come up.  We'd need some kind of structure document, and
   style guidelines to guide new users along.
3) We'd use moin's wiki -> docbook export function to then (at a suitable
   distance before release to allow translators time to translate the docs)
   have scripts/magic goo to pull the wiki information, convert to docbook, and
   then build edubuntu-docs packages from there, where they'd integrate into
   the existing yelp documentation.

This would satisfy the three requirements, and has the following benefits:

1) It means I don't have to spend time obsessiing over handbook docbook
   structure, but rather can simply obsess over wiki structure, which results
   in someone caring for the wiki on a regular basis.
2) Contributing to the handbook becomes as easy as editing a wiki.

I don't think getting the script structure in place is viable for karmic, but
we may be able to get the wiki in place, with an eye for getting docbookable
content for karmic+1.  As well, there's the issue of writing the scripts, and
all the glue associated, but that's just a programming excercise, and in my
view, not a significant hurdle.

I'd suggest we discuss it here, further, and finally at the next meeting.
In case it's not obvious, I'm willing to spearhead this to make it happen.

Thoughts?

Cheers,
Scott

-- 
Scott L. Balneaves | Perilous to all of us are the devices of an art
Systems Department | deeper than we ourselves possess.
Legal Aid Manitoba |     -- Gandalf [J.R.R. Tolkien, "Lord of the Rings"]