The cover page is the first thing a newcomer sees of the standard/specification and must therefor be informative and intuative. Besides the specific comments a general work-through is needed.
Is the color of the chapter headings correct?
A number of new page brakes would make the (pdf) cover page easier to read.
When looking at other OASIS specifications, most of them have different layouts and styles, so this is apperantly not to strongly enforced...
The current name of the committee draft/specification (Product Life Cycle Support DEXs Version R1) is not good. It's not only DEXs beeing standardized and the name is therefore misleading. A better name could be "DEXpub" or "OASIS PLCS DEXpub 2008:1" as the name for the upcoming specification/standard. With ‘DEXlib’ being the “DEX library” or “DEX development library/environment”, “DEXpub” would be the “DEX publication package”. Thereby avoiding the risk of confusion arising from naming the standard “OASIS PLCS DEXs”, which is the current writing. To be absolutely clear, - this specification/standard, which is a collection of approved DEXs, Templates, Capabilities, Schemas, Reference Data and additional guidance in the “PLCS Help and Information Pages”, should not be confused with one of the components of the standard (the DEXs) ,which now is the case.
The "Version R1" section should either be "Release 1" or "Version 1" or "Version 1.0", or as suggested above "2008:1".
Are these all relevant namespaces? What about "urn:plcs:rdl:std"? Are there more?
The text and link to the non-normative errata page "The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/documents.php?wg_abbrev=plcs " leads to the PLCS TC public documents folder. An errata file in here will be hard to find without knowing its filename.
The t.o.c. has a numbering style that is not used in the chapters below, e.g. "1.0" instead of "1".
Some of the links in the t.o.c. leads to sub-chapters within the cover page, and some to sections of the DEXpub. Suggestion, - Create sub-chapters for every line in the t.o.c. These sub-chapters should contain a short description of the target, and if appropriate, a link to DEXpub.
'PLCS DEX Main Page' should be 'PLCS DEXpub Main Page'
The t.o.c. has no direct link to Reference Data or to the PLCS Help and Information Pages. Wouldn't this be useful as the are listed as thing being standardized in this release.
The first paragraph has a reference to "OASIS Product Lifecycle Support (PLCS) standard". "OASIS" should be replaced by "ISO". The introduction must be very clear about the naming and separation of the different existing and up-coming standards.
The "standard" or "committee specification" (how should it be adressed?) is referenced to/named as both "OASIS PLCS DEXs Version R1" and "OASIS PLCS DEXs ed. 2008:1". A name must be set. With "DEXs" being used as the name of the complete published/standardised package, a reference to the concept of DEXs (Data Exchange Specifications) is made harder or confusing. Se also comments about title and subtitle namings. The ISO PLCS standard and its parts are also referenced differently in the text...
Are the keywords spacified by RFC 2119 used in the specified way within this commitee specification. If not, the RFC should not be referernced.
Is it information or data being exchanged by a DEX? What terminology shall be used through out the DEXlib/DEXpub/DEXs?
DEXlib has the functionality to link terms to the definitions in the terminology section. Shouldn't this possibility be used in the DEXs, e.g to link "ICAM" in the AAM section of the DEXs to its definition.
The section titles for "Business overview", "Business information overview", "Business information requirements" and "ISO 10303-239 representation" are not the same in the t.o.c. as they are together with the text. The name of the DEX is added in front of the above listed titles, e.g. "Business overview" in the t.o.c. becomes "Aviation maintenance Business overview". It is unnessesary to state the name of the DEX in the title. If considered nessessary, this should be for all sections. the use of leading capital letters is also not the same (se next comment below).
Through out both DEXs, the use of leading capital letters in the words used in titles is not harmonised.
Abstact section - first paragraph - last sentence: The boileplate text "The DEX represented information such as" would better read "This DEX specifies how to represent information such as".
Introduction section - Title: "Introduction" should be changed to "Introduction to DEXs and PLCS"
Introduction section - first paragraph - first sentence: This is the specification not a "specification for the ... specification". Sentence needs to be rephrased into e.g. "This is the xxx xxx Data Exchange Specification (DEX)".
Introduction section - first paragraph - second sentence: "A DEX specification..." should either be "A DEX..." or "A Data Exchange Specification...". The current text actually says "A Data Exchange Specification specification".
Introduction section - first paragraph: Is the described STEP objective true? "The objective of ISO 10303 is to provide a neutral mechanism capable of describing products throughout their life cycle"
Introduction section - second paragraph: The sentence "... what information can be exchanged and represented to support..." shouls change to "... what information is needed to support..."
Introduction section: The text in the first section is repeated by the bullet list below. A complete reoganization is suggested. Look at the modified D003 introduction file included in this review package for an example.
Related DEXs section: The boilerplate text that describes the related DEXs all uses aircraft as the only exanple of use. This need to be extended. Bothe DEXs also relate to DEXs not yet published as committee specifications or standards. This need to be explained and managed in some way.
Structure of the DEX section: the fifth bullet should remove the bold italic undelined term "business" in this quotation; "Business information overview provides a high level overview of the business information that can be represented by this DEX;"
Supporting material section: Suggest boilerplate text change to "Further information about DEXs, and technical details on how they are structured can be found in the PLCS Help and Information Pages". A reference to DEXlib is confusing. A reference to the published package "DEXpub" is possible but not needed.
Instead of writing "For the purpose of this document the following terms apply", I suggest "For the purpose of this DEX the following terms apply" or "For the purpose of this specification the following terms apply". The term "document" seems a bit misplaced.
A link to the 'Terminology' section of DEXlib at the the end of the Terms page could be useful if a user needs to understan terminology not specific to the DEX.
Boilerplate text both for the "within" and the "outside" scope statements are incorrect. "Data EXchange Set" (DEX)" should be "Data Exchange Specification (DEX)"
D011 uses "reportable item" and D003 uses "supported item"
Note: The correctness of the defined scope has not been reviewed or evaluated!
A suggestion for new text for the first section is in the file "DEX xxx - AAM.doc".
The first sentence of the 'Activity definitions' section; "The following terms are used to label activities:" should be replaced by something like; "The activity labels in the AAM model views above have the following definitions:"
The 'ICOM definitions' section; The term (abbreviation) ICOM needs to be explained or text rewritten.
The 'ICOM definitions' section; The first sentence "The following terms are used to label ICOM arrows:" should be replaced by something like; "The ICOM arrow labels in the AAM model views above have the following definitions:"
The actual definitions or the correlation with the included figures have not been reviewed!
The chosen notation in D011 is OMG UML Activity Model. It was earlier decided to use OMG BPMN for the process descriptions in DEXlib. Shall that descision be revisited? Isn't it important to use the same notation throughout DEXlib?! Shall OMG be contacted for a recommendation?
The Title should be "Information overview" not "Business Information Overview". Should change also in the navigation bar.
The "summary" figures in the beginning of each DEX should conform to the same graphical style.
The concept of "message" as beeing a construct for gathering one or more data sets conforming to a specified DEX has not yet been explaind in the DEX. A short description of this and a lin to the message template/capability would be useful.
The figure text should better be "Summary of .... information within the message container"
The title should be "Information requirements" not "Business Information Requirements". Should change also in the navigation bar.
The use of the term "Requirements" in the title is not clear and should be explained or changed for another term. Whos "requirements"? "Requirements" on what?
The link in the first section is incorrect. Should lead to the "(Bussiness) Information overview" section.
The first section should be refrased; "The Information overview section provided..."
The second header is different between the two DEXs. D011: "Information". D003: "Information Requirements overview" (better than D011).
The t.o.c (the use of headings) are quite different amongs the two DEXs. D003 has "hundreds" of sub-sections. D011 has two (2). They should be more similar.
The UML class models hasn't the same style, both in respect to amount of included information as well as graphical layout. One of the styles should be chosen. The D003 style is on FMV behalf considered to be the most attractive. The use of small models belov the overview model makes the reading easy.
The figure texts (D003-fig8 and D011-fig7) should follow the same style.
Both DEXs describe "Message", but in different ways. D003 talks about "Extraction_date" and "Contract". D011 uses "date_of extract" and "contract_identification". Both DEXs also describes "Task" and "Resource". This review has not gone into detail regarding differences between the description of these concepts in the two DEXs, but it's not unlikely that these sections have the same type of problems.
First sentence; The boilerplate text is not correct. This section doesn't describe how to represent a DEX. The DEX is the specification of how to represent data needing to be exchanged (a DEX would probably be represented as a "document" if described with 10303-239). Suggestion for new text; "This section provide a detailed description on how to represent task/operational feedback data as described in ([links to one or all of the three preavious sections]) using ISO 10303-239 PLCS.
Second sentance; Incorrect as per above, plus Templates, Capabilities and Reference Data are written with non-capital letters. Suggestion to join with previous sentence; ", using PLCS Capabilities, PLCS Templates and PLCS Reference Data."
Second paragraph; Reference Data and Reference Data Library are written with non-capital letters
Third paragraph; Is it Information or data being exchanged by a DEX. This is a comment also placed on a more genral level.
Third paragraph; The links included in the text are the same as those refered to within ([...]) in the first comment. Introduction needs to be "re-architectured".
Graphical styles are different in the two template/express diagrams (D003-fig19 and D011-fig9). FMV supports style in used in D003-fig19, except for the white boxes with "a" and "b".
There is no description of Templates or the template/express diagram, and there is no reference to a further description of Templates and Template notation in the PLCS Help and Information Pages. This is needed in order to give the reader a chance to fully understand the figure (this is perhaps in some extent also needed for the UML Class diagrams). Also the Template table should be explained, including the concept of parameters.
The structure beneath the figure (D003-fig19 and D011-fig9) are differernt between the two DEXs (D003 lack a list of the templates in the figure (fig9))
There is a considerable number of 'Parameter values' not yet allocated/defined in the Template table, or is the "?parametervalue?" notation a way of describing that any value could be used?! This should then be explained.
The Templates section should have a justfication/description of why the list exists, an perhaps have a link to the 'Info Pages'.
The URN-links doesn't lead to the specific class, only to the "Referernce Data Class Viewer" "All classes" view.
The table should show the class label, not the id, e.g. instead of "Access_description" the table shall show "Access description".
Further explanation about what i meant with 'Conformance to a DEX' is needed for clarity, possibly with a reference to the future Implementors Instruction section in the Info Pages...
A short explanation about why the list/table of EXPRESS enteties is included would be useful for clarity.
The Referernce Data Classes used by the DEX are not only listed in the 'Ref. data' section, but also here. Could a link to the 'Ref. data' section be enough?!
The name of this DEX should be "Operational feedback" or "Activity report" or ..., and the content should be adopted to this more general scope. Publishing a DEX with this name is not in the interest of the TC! Shall we later publish a "Ship maintenance" and a "Vehicle maintenance" DEX...?!
The term "reportable item" is used. Is this a well known term. Isn't the term "xxx candidate" used in mil-std 1388 a better and more general term? D003 uses "supported item" for a similar/identical concept. Se also the section discussing the scope statements (Commom to both DEXs -> Scope).
Further comments are for some sections included in an attached document containing a copy of the section, accessable using the provided link.
Three issues are displayed in the beginning of the scope page and should be removed.
"Aircraft" is used instead of a more generalized term.
The only activity yellow marked in the figure is "collect data and provide feedback", but also "Analyze support feedback" and "Extract and collate information" are described in the 'Activity definitions' section.
The term APSI is not a ICOM arrow and should not be in the definitions section. Possibly included in the terms section?!
The definition for the ICOM arrow "authorized task" is not included in the definitions section of the page but marked yellow in one of the figures.
The definition for the ICOM arrow "maintenance need" is not included in the definitions section of the page but marked yellow in one of the figures.
Figure 3 as written now, says you either perform "Sheduled Maintenance Activities" OR "Usheduled Maintenance Activities". Can't both these activities be performed after a sortie?! The descision diamond should be replaced by a fork (as used elsewhere in the figure). The fork at the end should instead be a merge with a condition such as [all planned activites completed] on the outgoing flow - otherwise the process will never reach the flow final.
Reportable Item Status - "Geographical Change"; Is the intention to use this DEX to track real time movements of equipment or is the intension to register chages to "base locations" or "operational locations". The text should perhaps discuss this in more detail.
Text above figure 5; "UML diagram" should be "UML class diagram".
figure 5 text; A "a" is to be removed.
There is no clear relations between the figure (figure 6) and the information elemments listed below. E.g. "Message wrapper" cannot be identified in the figure.
Could it be explained (if this is the case) that the actual data set beeing exchanged will be quite different depending on which of the listed activities, data is describing?
The text is aircraft focused and should be made more general The text also uses Business terminology, e.g STFs, SEMs and UTIs. Are the aviation general or used by a specific organisation?
The explanation of Engineering instruction.identifier and .type should be refrased.
Fault_status.status specifies allowed values. Should this instead be an example?!
Is "Standard_maintenance_task" a generally accepted term)? Or is it a Maintenance_task" classified as "standard" according to a business specific RDL?!
In the "Message" section, first sentence; "The information is exchanged as..." should be refrased "When information is to be exchanged between maintenance IT systems, it is exchanged as..."
The description of Message.message_type could be clearer...
Message.sent_to; Is a "Message" sent to a "person" only?
The name of this DEX would better be "Task" or "Task description", while the DEX itself is a specification (this comment is weak compared to the comment to the DEX 011 naming). FMV reccomend "Task". If D011 followed this naming it would be called "Aviation Maintenance Specification".
The identifier of the DEX is "task_set", The name of the DEX in the introduction is "Task Specification". D011 refers to the DEX as "Information related to a single task" (boilerplate inclusion). The naming needs sorting out
Further comments are for some sections included in an attached document containing a copy of the section, accessable using the provided link.
In the "Introduction to the Task Specification DEX", in the last 'Note', the phrase "a single message" is used. Should there be a reference to the representing message template or to the message capability (when completed)?
A suggestion for new text is in the file "DEX 003 - Introduction.doc".
the bullets need to be more descriptive in their wordings. One example is "task trigger (..examples...)" with no further text. A possibly better (at least more descriptive) text could be "Description of triggers (...examples...) that initiates the execution of a task". Most others need similar work.
The definition for the ICOM arrow "task procedure" is not included in the definitions section of the page but marked yellow in one of the figures.
ICOM arrow definitions are not listed alphabetically.
The DEX doesn't have a process description. Shouldn't this be a requirement even how simple the process is?
The DEX doesn't show an example of when in the process where data is packaged according to the DEX or when a data exchange could be supported by the DEX. Isn't this an important component of the process description for understanding the purpose and role of the DEX?!
In the figure 7; If the text makes a reference to the DEX, then "...task specification..." should be written "...Task Specification...", or even "Summary of the Task Specification DEX information"
To avoid misunderstandings, the name of the DEX should be written with leading capital letters and when "task specification" in general is discussed it could instead be refrased "specification of the task related information" or something similar.
The difference between a task and a task step in terms of descriptive information is not explained. It is also not clear weather several task steps can be difined within the same DEX. The writing "A task specification may be subdevided into task steps" is not clear.
In the Task section; The header says "Task" but the text discusses "maintenance task" only.
The use of leading capital letters is not uniform (through out this section).
Indention should be used to make the list of "detailed requirements" more readable (see DEX011).
The table of contents used in the ISO 10303-239 Representation section could also be used in this section
Figure 9; the class label says "Product" and the figure texts says "Product in Focus"
The "Task definition" section only discusses "maintenance task". This this the sole scope of the DEX?
Figure 16; The blue arrows are not nice. Convey this information in another way.
The Reference Data in the review package has not been through any of the intended review stages and are in general in a poor condition/does not conform to the guidance in the (not balloted) Reference Data Checklist in DEXlib. A detailed review of this part of DEXpub is not useful at this stage.
Links to the Referens Data Class viewer do not lead to the class referernced by the link, but to the top of the viewer page.
The text "DEXlib" existst in multiple places in the specification package out for review, but the relationship between DEXlib and DEXpub (OASIS PLCS DEXs Version R1) is not made clear.
Through out DEXpub, the use of leading capital letters in the words used in titles is not harmonised.
The name of the DEX should be shown in the navigation bar e.g. 'Task specification', now the identifier e.g. 'task_specification' is shown (see "D003 - Task specification" for more on this).
The navigation bar should not contain abbreviations. Suggestion;
- "Intro." should be "Introduction"
- "239AAM" should be "PLCS Activity Model"
- "Bus. Info. overview" should be "Information Overview" (see also 'Common to both DEXs' section in this review)
- "Bus. Info. reqs." should be "Information Requirements" (see also 'Common to both DEXs' section in this review)
- "239 rep." should be "PLCS Representation"
- "Ref data" should be "Reference Data".
- "Biblio." should be "Bibliography"
"Reference data" should be changed to "Referens Data"
When clicking the 'Home' button, it takes you to the 'Help/Information' section, which is confusing. Suggestion;
- Keep 'Cover' as it is, beeing the start for the specification
- 'Home' should be the position the user gets to when following the link in the 'PLCS DEX Main Page' chapter. It shall give a short description of DEXpub (and DEXlib) and contain a link to the start page of the 'Help/Information' section.
- The 'Help/Information' link shall load most of what's on the current 'Home' page (except for DEXlib/DEXpub introduction). from there the user may chose to further study the 'Help/Information' section, or to move to any of the other sections
All entries/links in the navigation bar except 'Cover' and 'Home' load an index or t.o.c in the left pane, while keeping the previously visited page/text in the main window, which is confusing. This should change according to one of the following ranked suggestions;
- A introduction page (specific for each area) should load in the main window, and the index/t.o.c. should load in the left pane
- A introduction page (specific for each area) should load in the main window that include a link which loads the index/t.o.c. in the left pane
How will we avoid getting comments to earlier approved parts of the standard when we release new DEXs, Reference Data or even perhaps only additional content in the Help & Info? Are links from the cover page to new components enough? Or is it perhaps a good thing to allow comments to the complete package at every release?!
Through out the 'Info pages', the use of leading capital letters in the words used in titles is not harmonised.
OWL concepts section; 'Individual' is explained and said to to be used for PLCS Reference Data, but this in not the case?! 'Superclass_of', 'Disjoint_with' is used for PLCS RD, but not explained.
The annotation properties 'OASIS_stage' and 'OASIS_revision' are not Dublin Core meta data and should therefore not use the 'dc' prefix.
The definitions of the PLCS components should be the same as in the Terminology section, with the difference that the name of the component should be included in the text when in the 'Help/Information' section, but not when in the 'Terminology section'.
There is a lot of text in the beginning of the 'chapter' that has no chapter title. A sutible chapter title should be inserted.
Section "The parts of ISO 10303 that are of relevance to PLCS"; In the text "FMV (Swedish Defence Material Administration)", "Material" should be "Materiel".
There is a lot of text in the beginning of the 'chapter' that has no chapter title. A sutible chapter title should be inserted.
Figure 1; Text in the figure says "PLCS Data Model" and figure text below says "PLCS information model". Diffrent terms might confuse. "Information Model" should be used
Figure 1; Style and color is awful...
Figure 1; The figure names DEXs not yet established. One good thing is that it referes to the "Operational Feedback DEX"...
Figure 1; The figure text should state that the model 'schematic'.
There is a lot of text in the beginning of the 'chapter' that has no chapter title. A sutible chapter title should be inserted.
Figure 1 and text above; Is it correct that a Capability "defines" Templates, or should it be "describes"? The 'Home' start page doesn't describe Capabilities as defining Templates.
There are two definitions of 'Capability'. The same style as for the DEX defiition should be used.One should be removed.
There is a lot of text in the beginning of the 'chapter' that has no chapter title. A sutible chapter title should be inserted.
Generally agreed Terminology principles (as used by ISO 15926 and described in the OASIS PLCS Reference Data Checklist) should be used regarding the format of the definitions, e.g. the defined term should not be used in the definition. The complete list of terms should go through a quick review if time doesn't allow a complete review.
The 'Terminology' section doesn't have a start page explaining it's use or content. Such a page would be better to load when the 'Terminology' field in the nav bar is clicked. From this page one could then chose to load the t.o.c. to the left pane. (I actually clicked the link three times without noticing that the index appeared to the left. I thought something was wrong... /MatsN)
Instantiation path section; A reference is made to the "help" section. Should be "Help/Information" or "PLCS Help and Information Pages".
Instantiation path section; The referens above is to a section referred to as "Reading Capability Templates". No such component or section existst. Correct link should be to the "Template instansiation path" section of the Tempaltes section of PLCS technical description section of the Help and Info pages.
The two comments above could also be valid for other, not reviewed Templates! A complete scan would be appropriate.