[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]