OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

plcs-tog message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [plcs-tog] Issue Resolution Request # 1


Hi,

Having spoken with our implementers, SME's & template designers, I would
like to summarise the views received at LSC.

The implementers believe that the template instantiation diagrams should
provide sufficient context for their use, without additional entities
which can make the usage unecessarily complicated and/or confusing.

The SME's can see that both positions are useful; i.e. a template which
is kept small & concise makes it easier to use; but that in certain
circumstances the extra entities saves time in looking up how/where it
can/should be applied.

Template designers spend considerable effort into designing a template,
in particular keeping the scope of the template at a manageable level
while allowing maximum reuse - which is a labour intensive business. As
with much else on DEXLIB the approach has evolved over time, hence some
templates are more in-line with current expectations than older ones.
However, the template specification does provide enough scope for
documenting the additional information, but requires a little more
effort to do.

----Discussion ---

For implementers, what can be confusing is the subjective choice of
entities provided - such as showing a single entity out of a select type
list. For assignment templates this about 99% of the cases where
additional entities are shown. Thus, the defacto purpose of using the
entity shown has been to select an item from the select type list -
usually to continue an example that is also being constructed.

The original purpose of the template EXPRESS-G model diagram was to
present the entities which would be instantiated by the template being
specified - likewise with the template instantiation diagram. The
consolidated model & instantiated diagrams were to show how the template
would appear in final form (as it were). Hence, the template EXPRESS-G
model diagram should (ideally) show the contents of the select type
list, and the template instantiation diagram should show either one item
(marked appropriately as out of scope) from the select type list or none
at all.

However, for the former, this is somewhat impractical due to the
size/length of the select type lists involved. It was also decided early
on not to show the select types (graphical symbol) on the diagrams - but
this may be an opportunity to change this. Note the select type list is
used as an input parameter type in this typ of template.

Two other reasons why templates can become complicated include;
- the addition of relationship entities which are not instantiated by
the template. However, because no separate template has been created to
achieve this, it may seem at the time useful to provide this additional
information. However, this creates more problems later (to remove the
information & include references) when a separate template is/should be
created for this. 
- another reason that affects template complexity is the number of
optional templates used to characterize the template being defined.
These should not be provided on the template EXPRESS-G model diagram but
rather within the characterization section or additional guidance at the
end, (preferably using the shorthand template notation). The definition
of characterizations is easily confused with optional attributes within
the template - but the two should be kept separate & distinct (optionals
should have a default set).

----Recommendations -----

Update/Clarify template guidelines subject to agreement with above
suggestion/discussion.

I think this is more of a quality issue than one about right and wrong;
but modifying what we have would be an expensive thing to do, so I would
suggest that where these situations occur, they are documented as
warnings which can be recorded as minor documentation issues (with
recommended action) and used as an input to the next template
modernisation phase. 

I think new templates, however, should adhere to the guidelines.

Regards,
Tim

-----Original Message-----
From: tai@sfk.mil.no [mailto:tai@sfk.mil.no] 
Sent: 12 June 2007 11:16
To: plcs-tog@lists.oasis-open.org
Cc: tai@sfk.mil.no
Subject: [plcs-tog] Issue Resolution Request # 1

Issue Resolution Request no.:	1
Issue type:	Check list issue

Attached is the documentation on Issue Resolution Request # 1.
There are two positions in this case:
1.	Keep the templates as small as possible by only showing what is
in scope and hence will be instantiated by the template.
2.	Show the template with entities within scope as well as entities
related to its scope. Hence show more than what will be instantiated by
the template.

Effect of the decision on work already performed will in both cases be
that templates will have to be adjusted. Either by removing or adding
stuff from each template. In the case of adding this clearly must be
corrected straight away. In the case of removing the urgency is not as
great  provided each template is provided with a note to disregard the
greyed areas.

When deciding we should keep in mind what will serve the intended user
of the templates best as well as avoiding overlapping documentation with
possible inconsistency as a result. Possible inconsistency will be a
bigger problem in the case of manual generation of documentation.

 
The TOG Chair recommends the following approach:


Each member of the TOG is invited to forward his/her point of view to
the TOG via the mail exploder.
After 5 working days, the TOG holds a Telecon on the issue.



Best regards 

Tor Arne Irgens
TOG Chair 
DISCLAIMER: ***SECURITY LABEL: NOT PROTECTIVELY MARKED***   The information in this message is confidential and may be legally privileged. It is intended 
solely for the addressee.  Access to this message by anyone else is unauthorised.  If you are not the intended recipient, any disclosure, copying, or distribution 
of the message, or any action or omission taken by you in reliance on it, is prohibited and may be unlawful.  Please immediately contact the sender if you have 
received this message in error. This e-mail originates from LSC Group Ltd. Registered in England & Wales No 2275471 Registered Office: Devonport Royal Dockyard, Devonport, 
Plymouth, PL1 4SG, having a place of business at Lincoln House, Wellington Cresent, Fradley Park, Lichfield, Staffordshire WS13 8RZ and at Catherine House, 
40a St Thomas Street, Weymouth, Dorset DE4 8EH. VAT number: GB 655 1330 55. 


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]