[Computerbank] Computerbank Documentation Project

[Patricia Fraser]

Hi all,

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 

http://lists.sourceforge.net/lists/listinfo/cbdoc-train

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 
flexibility.

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 

http://www.gnu.org/copyleft/fdl.html

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.

Cheers!
Your Training Co-ordinator
----------------------
Patricia Fraser
trish at thefrasers.org
www.computerbank.org.au
-----------------------