[Psidev-ms-dev] Spec document format

[Andy J. <aj...@cs...>]

Hi all,

 

Apologies if you receive multiple copies.

 

In the Gel group, we are shortly going to start writing the spec document
for GelML. Before starting I would like to have a quick discussion about the
format of the document because it would be good if we adopt a similar format
across all documents produced from now on. I see there are various current
specs that ought to be considered.

 

- Autogenerated docs for MI: http://psidev.sourceforge.net/mi/rel25/doc/

- Draft of mzData spec:
http://psidev.sourceforge.net/docstore/browse.php?sess=593acb54e566e0e2e0808
278349f8294
<http://psidev.sourceforge.net/docstore/browse.php?sess=593acb54e566e0e2e080
8278349f8294&parent=7&expand=1&order=name&sortname=ASC>
&parent=7&expand=1&order=name&sortname=ASC

- We've also just put out the internal draft of the FuGE v1 specs
http://fuge.sourceforge.net/Version1Candidate/. The FuGE spec is divided
into two documents:

1.	A user guide which has general tasks, class diagrams and general
description of the model.
2.	A reference manual (UML + XML Schema), which is autogenerated by an
AndroMDA cartridge I've written.

 

The difference between MI/mzData and say, GelML, is that we have primarily
developed a UML model with a defined mapping to the XML Schema. Therefore
the specs are likely to focus more closely on the object model. I would like
to propose that for models developed on top of FuGE, it might be
advantageous to adopt a similar format to the FuGE specs, whereby:

i)                 The reference manual covers both the UML and XML Schema,
and it is autogenerated, therefore minimal work.

ii)                I can produce a template "user guide" which can be
populated manually. All the models extending from FuGE would then have
consistent specs. The user guide could include some of the facets of the
mzData spec, such as Goals, Requirements and Appendix on CV usage.

 

Could group chairs take a look at the draft FuGE specs and comment on the
suitability of this format (sections 3 to 5 of the FuGE user guide would not
be applicable). I guess we could adopt different policies for FuGE-based and
non FuGE-based format if necessary?

 

Best wishes,

Andy