list archives . users mailing list
 

Subject: Re: GSDF documentation

Date view Thread view Subject view Author view Attachment view

From: Mario Antonioletti (mario@epcc.ed.ac.uk)
Date: Mar 19, 2003 18:16

Hi Guy,
       Once again thank you for your feedback. We have been refactoring
the way that the configuration for the GDSF is done which, we hope, will
be simpler and inherently more powerful. I know that this does not
resolve your current problems but we hope the next release will be
improve on these matters.

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

I am interested by this point. Normally pdf is highly readable on
screen, apart from the odd latex conversions where cmr fonts are used.
For long documents it is tiresome - is this what you mean or are the
fonts really rendered badly. If so this is something we should look
into. Also, do you think the documentation should be provided in some
other format, e.g. html? I've be interested to hear your view on this.
 
> 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.

Personally I don't have a problem with the typography. I take your point
about the examples breaking the flow but we thought the illustrations
would be helpful and if you align them with the surrounding text the
line wrapping would be more distracting. Hopefully the next release will
not require so much illustrations regarding usage.

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

We can try to do this for the next release. Configuration though, we
think, will be somewhat simpler though.

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

The intial GDSF configuration file had a lot of place holders for ideas
that were emerging in the OGSA-DAI group as well as the GGF DAIS working
group that were not fully worked through and we hoped to expand on in
future releases. Again, I think the GDSF configuration for the next
release will be simpler and will have no such place holders. If, after
the next release comes out, you disagree, feel free to send me an email
as grouchy as you want reminding me of everything you said.

Thank you for taking the time to look over the stuff though. We hope to
take it on board and improve the quality of what we produce ... thank
you,

                        Mario

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

-------------------------------------------------------------------------
|Mario Antonioletti:EPCC,JCMB,The King's Buildings,Edinburgh EH9 3JZ. |
|Tel:0131 650 5141:mario@epcc.ed.ac.uk:http://www.epcc.ed.ac.uk/~mario/ |
-------------------------------------------------------------------------

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