Some comments about the Dev Manual

And hi, once again :-)

I would like to comment several issues before we publish both new versions of the User and Dev manuals.

There are several sections in the Dev Manual that need to be developed but Abel and I need your collaboration to make it.

First of all, I want to note that I named the checker as "W3C mobileOK Basic Tests 1.0 Checker (Beta Release)". The 1.0a (which would now turn into 1.0b) might lead the audience to a mess as 1.0 is the version of the mobileOK Tests and the 1.0a/1.0b names the version of the checker). So I would call it like I said before, removing the text in brackets -Beta Release- when we release the final version of the checker.

I'd also like to note that I repeated the section "Download and installation" in both manuals, as it does not make sense at all that someone needs to get to the User Manual just to get the URI to download the JAR file. Besides, I have changed the way in which we point to the files in the CVS: the manuals point to the root of the CVS space for the Checker and also to the actual version of the JAR file available when the (current) manual was released.

Now let's discuss some sections of the Dev Manual.

Issue #0
--------
"Lessons learned" section removed. Section "Implementation decisions" would be enough. Do you agree?

Issue #1
--------
In what regards to the section 3 -Software Requirements (Use Cases)- , which was taken from a thread started by Jo in http://lists.w3.org/Archives/Public/public-mobileok-checker/2007Mar/0009.html, we have removed the text saying:

"In order to minimise possible version drift between the checker and external validators on which it depends, it MUST include an option to use those services remotely (e.g. validator.w3.org)."

I am not sure whether the publication of the tool in the w3.org space part is one of our tasks? If so, I will add such text. This text would be then subsection 4 in section "3.2 Conformance".

Issue #2
--------
In section "3.4 Structure", some words have been deleted in the point #4. After the sentence "The checker will be written in Java", it said "a programmatic interface with bindings initially to Java [and SOAP?]. [Are we going to write something other than Javadoc by way of documentation/design?]".

Should we publish this without the SOAP reference? Does it make sense to reference the manuals in the manuals themselves? I would leave it as it shows in the doc.

Issue #3
--------
In section "3.4 Structure", the final sentence in subsection 5 is highlighted: "Specifically this should not be seen as a project to create the W3C mobileOK checker".

Haven't we made up our minds?

Issue #4
--------
Section "3.4 Structure" strikes back. Subsection 6 says "The format of this intermediate document will be specified separately, and will use existing representations [like RDF/HTTP] where possible.".

You can see the text between square brackets highlighted. Should we remove it? Or just show it and then justify why we could not use HTTP in RDF? Maybe it should be explained getting the "Lessons Learned" section in the doc or it would be enough to do it in any other section.

Issue #5
--------
Section "3.4 Structure" again --> Two sentences in subsection 7 removed. They said:

"It must be possible to add tests without recompiling the checker."

"It must be possible to replace sub-components (such as remote validation steps) by configuration option"

First sentence is not true. A pair of modifications in the code are needed in order to do that, if I am not wrong. It might be explained in the resurrected Lessons Learned or somewhere else... or we might just let the sentence in invisible ink.

The second one is not true either. We abandoned such a level of modularization long ago. Same applies (leaving the sentence and explaining why we did not do it or just leave the text out of the doc).

Issue #6
--------

3.5 Process --> This wording was removed 

"The project will create documentation explaining the trade-offs between performance, flexibility and maintainability in making those choices. [this is a proxy for saying it will be cheap, fast, good, flexible, maintainable ...]"

Maybe a "Conclusions" section?


Issue #7
--------

4.3.3 Some notes about XSLT --> More info on this?


OK. Discussion started.
As decisions are taken about all the issues, I can get a new version of the Dev Manual in 1 or 2 days, so that the manual is ready for the Beta Release.

Best regards,

Nacho



******************************************
Ignacio Marín Prendes
Device Independence Activity Lead
R&D Department
ignacio.marin@fundacionctic.org
www.fundacionctic.org
Fundación CTIC -Centro Tecnológico de la Información y la Comunicación-
Parque Científico y Tecnológico de Gijón
Edificio Centros Tecnológicos 
33203 Cabueñes - Gijón - Asturias
Teléfono: 984 29 12 12
Fax: 984 39 06 12
******************************************
Este e-mail y cualquiera de sus ficheros anexos son confidenciales y pueden incluir información privilegiada. Si usted no es el destinatario adecuado (o responsable de remitirlo a la persona indicada), agradeceríamos lo notificase o reenviase inmediatamente al emisor. No revele estos contenidos a ninguna otra persona, no los utilice para otra finalidad, ni almacene y/o copie esta información en medio alguno.
Opiniones, conclusiones y otro tipo de información relacionada con este mensaje que no sean relativas a la actividad propia de CTIC deberán ser entendidas como exclusivas del emisor.
--------------------------------------------
This e-mail is confidential and may contain legally privileged information. If you are not the intended recipient it may be unlawful for you to read, copy, distribute or otherwise make use of the information herein. If you have received this e-mail in error, please contact us immediately. Fundación  CTIC will accept no liability for the mistransmission, interference, or interception of any e-mail and you are reminded that e-mail is not a secure method of communication.

Received on Sunday, 3 February 2008 19:07:43 UTC