[Modeling] Document structure

Radovan Cervenka rce@whitestein.com
Thu, 20 Feb 2003 19:14:02 +0100

Dear Marc-Philippe,

> >   a.. <Title>! {name of the area}
> Agree but maybe we can use a path and a name, as a consequence, we can
> have a first idea of the use of the document and we can have several
> documents with the same name but different paths

What paths do you mean? The modeling areas are given by Jim's list (see
http://www.fipa.org/activities/modeling.html, 3rd point of the Status
section) and they seem to be unambiguous. For now we use just a flat
structure (list), and I see it as sufficient.

> >   b.. Overview! {description of the area to-be-modeled. What are the
> > problems, how they are usually modeled, what modeling elements are
> > used by the currently used techniques, what is the applicability
> > during the development cycle of MAS, etc. - informally}
> I would like to add, what are the redundant solutions?

Yes. Every relevant information can be included here. Therefore I put "etc."
at the end of sentence.

> >   c.. Abstract Syntax! {UML diagram(s) of proposed metamodel; UML 2.0
> > metamodel can be taken as the basis}
> Except the name of the field, I agree with you

Which one would you use instead? Metamodel?

> >   d.. Class Descriptions! {class-by-class description of the
> > metaclasses. For each class to specify:}
> >     a.. <Name>! {name of the metaclass}
> >     b.. Description! {textual description of the semantics}
> >     c.. Attributes {a list of contained attribute descriptions}
> >     d.. Associations {a list of related relationship descriptions}
> >     e.. Constraints {a list of applicable constraints (called also
> > well-formedness rules), described firstly in English then in OCL}
> >     f.. Notation {description of the notation (concrete syntax)}
> >     g.. Presentation options {description of alternate notation}
> >     h.. Examples {examples of using an element}
> b. Description: do we speak about the description of the class or the
> semantics of the class, the former is usually a natural language
> document, the latter a formal definition

I was thinking about two sections: description and semantics. But, they are
more-or-less about the same, because semantics is defined in natural
language as well. Therefore I put them into one. But no problem for me if
people decide to have them separated.

> Once again, we do not feel obliged to follow strictly UML and maybe we
> can have several other fields in the class description

I agree. Do you have some ideas about further fields?

> >   f.. Diagrams {a chapter describing proposed diagrams; for each
> > diagram type to specify:}
> >     a.. <Diagram name> {a name of the diagram}
> >     b.. Description {Description of the diagram content (what elements
> > are comprised) and applicability (why and when to use this diagram)}
> >     c.. Examples {some sample diagram(s) and description of their
> > semantics}
> >   g.. References! {a list of used and/or relevant references; papers
> > and Web pages as well; reference list should be structured according
> > to different sources, sub-areas, etc.}
> and above all, what elements from the superstructure the diagram uses or
> maybe you put this information in class description

Hmmm... Originally I was thinking about putting this information into the
Abstract Syntax/Metamodel section. UML superstructure classes will be put
into the diagrams and explained, how to use them. But there can be a
separate section, describing how "pure" UML modeling constructs are
"harmonized" with new ones, in order to model MAS-specific aspects.

> XMI might be a good idea as long as we share some strong links with UML,
> else it would be more efficient to define our specific language (based
> on XML?)

I'm afraid we will have not enough time to define our format...

> Tool? Well, I strongly agree that Rational Rose is a good solution, my
> concern is money, what to do if your team does not consider this
> expensive tool as essential for the team? Does it mean I am out for
> several things?

We will see... In the worst case we can exchange just pictures... But Rose
is winner for now :-)


Radovan Cervenka | rce@whitestein.com
Whitestein Technologies | www.whitestein.com
Panenska 28 | SK-81103 Bratislava | Slovak Republic
Tel +421(2)5443-5502 | Fax +421(2)5443-5512
If you are not the intended recipient of this email,
you are not authorized to make any use of it;
please delete it and notify us by return email.
Thank you.