[Computerbank] Documentation (long)

[David Hatton]

Hello Jo-Anne,

- my 4c worth on Documentation :-)

I have been involved with getting together a coherent set of technical
documents to support daily operations in hardware assessment, software
installation and final configuration of computers being provided for
recipients out of Computerbank in Melbourne. 

This is a work in progress and there is still room for considerable
improvement, but I thought it might be useful if I summarised some of
the problems and some possible solutions.

I put my hand up for the cb-doc group mainly in order to keep in touch
with how that group was producing the training documentation, so as to
avoid significantly different ways of producing training and technical
documents. I also wanted to use the original HTML 'Cheatsheets' written
by Frank Copeland (and others ? - not sure) as a basis for a more
complete set of technical docs.

One of the first problems is that of producing different forms of
technical docs for different environments - for example printed docs
for the volunteers to use in the workshop and html docs for the cbv
intranet.  I took the view that a single source file, convertable into
the different formats, was the way to go - then you only have to change
one master file and regenerate the others from that file.  This is
particularly important for technical (and probably training) docs as
they tend to change frequently, and its relatively easy to keep the two
formats in sync, particularly if you are also using a revision control
system.

The other main constraint was that it would be a big advantage if we
could use Linux applications for all the documentation work, as this
would generally allow wider participation from Computerbank people.

It turns out that there is an immediate need at cbv for two forms of
technical documents, a small 'booklet' (half A4 size) printout for
workshop use and a standard HTML file to put on the intranet for
general perusal.  The printout could also be formatted as a full size
A4 page if required for workshop volunteers who might need it.

Initially, if I recall correctly, the cb-doc project considered using
Docbook as the standard for producing the training docs. I also though
that this would be the way to proceed for the technical docs, but there
were practical difficulties to this approach.  Essentially, it seems to
me that using docbook requires the following:

 -   becoming familiar with the Docbook markup definitions and how to
use
     them

 -   Becoming familiar with a text editor which has at least some
     support for writing using Docbook definitions.

 -   Working out what to write!
 
Someone who volunteers for writing documentation would ideally need to
climb the steep (some may say nearly vertical) learning curve of three
separate tasks at the same time. :-)

As the need for some technical docs was becoming urgent, I looked around
for a quicker solution to get docs "out the door".

To cut a long story short, I ended up using the Ted word processor to
generate both postscript (print to file option) and HTML versions of a
document. This allows the (hopefully sparing) use of basic text
formatting such as bold, underline and italic to emphasise various
important points and separate the display of computer input and output
from the general narrative. The master file was kept in rich text
format, which is the native format for Ted. The HTML generated was quite
reasonable, but needed some minor tweaking, something I want to improve.

To print out the document in 'booklet' form, I used the mpage program to
print out suitable sequences of pages on A4 sheets - mpage makes it
possible to use non-duplex printers for this task, as well as duplex
printers. One catch here is that you need to make sure no-one else wants
to print if you are using a non-duplex printer!
 
Both Ted and mpage are available in the standard Debian distribution,
and probably most of the other Linux distributions also.

Other editors/textformatters/printout tools could of course be used,
provided that the sequence is kept the same - that is - master file in
rich text format - printout generated from master file as postscript -
web page generated from same master as HTML.

With this scheme, the master files could be kept on a central computer
in a revision control system (either cvs or rcs) and printouts and web
pages easily produced as required.

There is another writers tool which may be worth a look, and that is lyx
(or klyx if you are using the KDE desktop).  From a very brief first
look, it seems to offer a more structured approach to writing a document
with a reasonably 'friendly' word processing interface. I'd be
interested in hearing from anyone on the list who has used either lyx or
klyx.

As to the types of technical documents, I am working on the assumption
that we need two different sets, namely :

 - A simple checklist for experienced Linux people
 
 - A detailed guide for people new to the task, with sometimes limited
   Linux background.
   
Together with John Haberman, I have put together some guides (hardware 
assessment, installing Linux, and carrying out the final configuration
for recipient machines) and a checklist or two. Also, Penni Diffey is
working on some guides for setting up a limited range of printers and
(I think) modems.

I intend that these docs be further refined in the light
of experience and updated frequently.  Once they are reasonably
complete, I would be quite happy to post them on the web site if that
was thought to be appropriate.

It may turn out that using Docbook is better for the medium to long
term production of documentation - I think it would depend on the
whether the ultimate destination of the documents is to be limited to
Computerbank and kindred organisations or available to the wider Linux
Community in a standard (Docbook) format.  If this is the case, we will
need to ensure that a Computerbank group (cb-doc?) set themselves up to
cope with this task and provide guidance to other interested people.
Also, the short-term practices outlined above may need small changes in
the interim period to allow easier conversion to docbook format. 

Hope this helps.

David H.

-------------------------
David T. Hatton
(davidth at melbpc.org.au)
-------------------------


Jo-Anne wrote:
> 
> Hi everyone
> Some of you will know me, but I will be a new name to those of you
> outside Victoria. I am both a user of Computerbank services and a
> volunteer at Computerbank. I am currently studying Technical Writing as
> part of my Diploma of Professional Writing and Editing. My final
> assignment for the year involves writing a case study on the use of
> documentation in a company or organization, so I am doing mine on
> Computerbank.
>         I would greatly appreciate input from everyone associated with
> Computerbank about the documentation in the organization. I will post
> some basic questions and hope that as many of you as possible give me
> some feedback.
>         This is also a good opportunity for the subject of documentation to be
> discussed and maybe create the incentive for more people to contribute
> to the creation and maintainance of documentation within Computerbank.
> 
> Here are a few subjects I would like to know more about.
> How important do you think documentation is to the organization.
> Should there be more of any type of documents?
> Should there be more cheat sheets? If so what topics should be
> documented?
> Have you ever read any of Computerbank Policy documents?
> What documentation from Computerbank have you used?
> Did you find it effective ? Why or why not?
> How is the documentation in Computerbank created?
> Who creates it?
> Who can make changes to documentation?
> Who decides what documents will contain?
> Who must approve of any documentation created?
> How is the documentation distributed?
> Who has access to particular types of documentation?
> Is Computerbank documentation widely used?
> Is Computerbank documentation effective?
> What changes would you like to see in the way documentation is used at
> Computerbank?
> 
> You get the general picture... answer one, answer them all or tell me
> something else; but, please answer me ASAP. (Yes I have put this off too
> long and the due date is drawing near. )
> 
> I look forward to some interesting discussion of this topic.
> If you have something you would like to discuss with me in private
> please contact me at jo_bianchi at dingoblue.net.au
> Thanks
> 
> Jo-Anne Bianchi
> _______________________________________________
> computerbank mailing list
> computerbank at lists.linux.org.au
> http://lists.linux.org.au/listinfo/computerbank