list archives . users mailing list
 

Subject: GSDF documentation

Date view Thread view Subject view Author view Attachment view

From: Guy Rixon (gtr@ast.cam.ac.uk)
Date: Mar 19, 2003 17:22

I've been trying to configure a GDSF using the document
OGSA-DAI-USER-UG-GDSF-v1.0 as a guide. I find that document suprisingly hard
to read and follow, given the manifest care with which it's been written. I
think I'm held up by several specific problems:

1. The document is in PDF. That means that it can't be effectively read
on-screen but has to be printed out.

2. I find the typography rather distracting. I think details like over-use of
bold face and code-samples that break the indentation pattern make it hard to
read.

3. The linear flow - i.e. the fact that the entire configuration-procedure is
in one chunk - makes it difficult to check things. I personally would find it
easier to use the document if there were brief lists of steps refering to
detailed sub-procedures in separate sections.

4. There are many steps in the procedures like "Provide a GDSF:PhysicalSchema
element of the form..." followed by an example with no explanation of the XML
elements or attributes. This translates to "You mustn't write exactly what
we've put in the manual, but you must write something very similar according
to precise rules we've hinted at but won't tell you", which is awkward for
beginners. Basically, the guide badly needs a description of the XML
vocabularies. If it had that, the detail in the procedures could be reduced.

Guy Rixon gtr@ast.cam.ac.uk
Institute of Astronomy Tel: +44-1223-337542
Madingley Road, Cambridge, UK, CB3 0HA Fax: +44-1223-337523

Date view Thread view Subject view Author view Attachment view
webperson@nesc.ac.uk