RE: Some comments about the Dev Manual

Hi Sean,

Thanks for your quick response.

I am OK with that. There is no problem with the amount of text in 4.3.3, I just wanted to make sure whether someone wanted to add more stuff to it.

We'll commit both docs in both formats to the CVS so they're ready for the beta.

Regards,

Nacho


-----Mensaje original-----
De: Sean Owen [mailto:srowen@google.com] 
Enviado el: lunes, 04 de febrero de 2008 0:10
Para: Ignacio Marin; public-mobileok-checker@w3.org
Asunto: Re: Some comments about the Dev Manual

Sorry to be brief, I am writing from a phone.
My opinions are:

1. I would not add new text and not restore the paragraph that was removed.

2. Remove soap references

3. Remove this sentence

4. Remove the last part of the sentence, starting with "... And will
use existing ..."

5. Remove both sentences

6. Remove this paragraph

7. Is the issue that 4.3.3 has little content? Remove it then I think


I am sure all the other edits are good. With this concluded I will cut a beta.





On 2/3/08, Ignacio Marin <ignacio.marin@fundacionctic.org> wrote:
>
> 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 Monday, 4 February 2008 08:55:19 UTC