[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Computerbank] Computerbank Documentation Project
It's time for an update! Warning - it's a *little* bit long. We're
looking for a coule of particular skills, which are *right* down the
bottom - so please read all the way!
At the last committee meeting, Computerbank Vic decided to start up a
sourceforge project to do ongoing documentation of what we do,
beginning with training documentation and hopefully adding policy,
procedures &c in due course.
As training co-ordinator, I have the happy job of project admin! So, a
project has been opened and approved on sourceforge, called cbdoc. Our
team currently includes Kylie, Grant & Penni Diffey, Jacqueline
McNally, Simon Porter, Jo-Ann Bianchi and Peter Eckersley (and me). (I
am hoping to include John Clark and Huw Greenhough *if* they will get
registered and send me their sourceforge login names!!!)
Our project has a mailing list. You don't have to be one of the project
developers to be on the list; we're happy to have people joining the
discussion, so if you would like to be on it, please let me know and
I'll subscribe you, or go to
and subscribe yourself. If you are a member of the project and you
haven't received a mail from this list today or yesterday, it's because
you haven't subscribed! Please go and do it!!
If you would like to be a project developer, please register as a user
on sourceforge; go to http://sourceforge.net and click on New User at
the left and follow the prompts. You might know nothing about our
policy or training but be a wizard editor - we could use you! You will
need some software tools to do this - I can help you there, so let me
know if you need it.
If you already have documentation (released under GPL, FDL or an
appropriate OS licence only, please!) that might be useful, please let
us have it or let us know where it is! Our only caveat is that it
should be in text or html format - it needs to be really wonderful for
me to go to the trouble of converting it and messing about with
millions of images. If there are images, I would prefer that they are
not embedded in the document, but separate files; zip or tar the
collection and send them to me personally, so I can put them in the CVS
tree for project people to look at, or send me a URL so we can all look
at the doc.
What are we up to now? We're at the design development &planning stage.
Since what we're writing needs to hang together as a manual or set of
manuals, we will first of all plot a development course for ourselves.
This involves working out all (or as many as we can) of the separate
pieces of learning information our trainees need to have access to at
various levels, and split these things up into separate tasks that can
each be written up as a how-to, and which howtos need to come first,
and which depend on others already being available. Of course we will
forget things, or find things out later, but we will design so things
can be added at any time - cbdoc will always be a work in progress.
Once we've done that, we can work out what needs to go around the
learning units in the way of documentation standards (in case this team
ends up severally or together under a bus), trainer notes, course
notes, trainer training and so on. Again, this sort of thing will
probably need continual development, so our framework will allow for
This design phase should all be sorted out within the next couple of
weeks. Then we start writing up the howtos and putting the book
together block by block; as soon as howtos are ready to use, we'll
release them, even if the book is mostly bones and not much meat
(excuse mixed metaphors - 'sFriday!).
There's a strong possibility that we'll release the whole thing as a
package at some point, so a project member who knows something about
packaging would be a great asset!
We are also looking for anyone who knows anything about a package
called scrollkeeper. This is apparently a package which can be used to
organise document presentation under a browser. Note: I will be
approaching the scrollkeeper people myself - I don't actually need any
URLS! It would be great if we had a person on our team who already
knows what to do with it, particularly since it would be nice not to
have to reorganise the cvs tree to make use of it, if it works out okay.
We'll be releasing all CB documents under the GNU Free Document
Licence; for a look at this go to
Many thanks to Tim Price for pointing the way on this one. To do this,
we must release all documents in an open format, so we will be using
docbook; this is a documentation standard which uses SGML, a tag-based
text markup language which can be converted readily to HTML or text
publishable (printable) format, and is in wide use for documentation in
the open-source community.
We'll do an announcement each time we pass a milestone; expect the
first one on or around July 20th, as we move from design to writing.
Your Training Co-ordinator
computerbank mailing list