[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Comments on "Artifact Identification Requirements 1.0", WD 15,30 June 2005
- General: metadata items and either explicit or implies formats are described in three places: 3.2 Name Component Definitions (says "definitions are in the order used as name components"), 4. Required Metadata for Artifacts, and 5.3 "Constructing Specific Artifact Identifiers. Distinction between "artifactName" and "ArtifactIdentifier" is not clear. Why two things? Suggestions: o Do not distinguish between the artifact identifier and artifact name, and use one name. Both should match the filename under which the artifact is stored, except that the file name should have -[language]-[format] appended. Section 5.3 suggests that perhaps the file name also differs in having the [tcShortName}- prefixed. o Combine Sections 4 and 5.3. Remove "definitions are in the order used as name components" from the introduction to section 3.2. o Have a chart like Appendix C be the normative form, with the textual descriptions as explanation of the chart. The chart can indicate which components are required for different types of identifiers (if there needs to be a distinction), and can indicate when abbreviations must/should/may be used and when not. - Omission: Conventions for titles of documents. Suggestion: o All words except prepositions and internal articles capitalized. o First line of title should be consistent with "product" plus "artifact type" plus "descriptive name" followed by ProductVersion with no preceding "v" or "V" or "Version". Example: XACML Profile for Role Based Access Control 2.0 o Second line of title should be non-abbreviated [Stage] [Revision] "," [Date] where [Date] is in DD MMMM YYYY format: Example: Working Draft 15, 30 June 2005 - p.1, line 2: Title: this is not a specification of "Requirements", but an actual specification or guidelines. Suggested title: "Artifact Identification 1.0" - p.1, line 5, Artifact Identifier: does not conform to Section 3.2 "Artifact Type" or Section 4 "Required Metadata for Artifacts". Suggested Artifact Identifiers (depending on response to p. 1, line 2): ArtifactIdentification-v1.0-spec-wd-15 ArtifactIdentificationRequirements-v1.0-req-wd-15 ArtificateIdentification-v1.0-guidelines-wd-15 - p.10, lines 264-271, Artifact Type: Appendix C lists several other types, and these should be included here. A more complete list, with standard abbreviations, is better than a minimal list in this case. Suggested additions: o Conformance Tests - "tests" [or "ct"] o Interoperability - "interop" o Whitepaper - "wp" o Test Assertions - "tests" [or "ta"] - p.12, lines 329 and 343-344: "artifactName" and "descriptiveName" both talk about using a "descriptive name". "artifactName" itself is not listed in Section 5. Suggestion: Change lines 328-329 as follows: Each artifact MUST contain the ArtifactIdentifier consisting of the following components expanded below: artifactName:[tc]=[product]-[productVersion]-[artifactType]-[stage]-[descriptiveName]-[revision] - p.13, lines 369-371, Common conventions: mention explicitly that underscores MUST NOT be used with reason that they are hard to see in browser links. Suggestion: Change line 369 to say: "Within components, spaces and underscores MUST NOT be used." - p.13, line 390, ArtifactIdentifer: Why is "tcShortName" not part of the ArtifactIdentifier? This does not agree with p. 12, line 332. - p.14, line 395, DescriptiveName: says "MUST be included if no other metadata is included in the ArtifactName", yet earlier sections said that other components such as "product", "version", etc. MUST be included in the Artifact Name." Suggestion: Remove "if not other metadata is included in the ArtifactName." - p.14, line 401: should a URN contain a value for "Form"? I can understand a URL, since a physical document in some specific format will be located there, but a URN is an identifier and not a pointer to a specific document with a specific format. - p.15, line 449: typo: "desriptiveName" should be "descriptiveName" in two places. - p.16, lines 480-485: is "document-id" the same as "descriptiveName"? - p.16, lines 480 and 482: these two variations differ only in that the first has "tc:[tc-id]" as the prefix, while the other has "specification:[specification-id]" as the prefix. It is hard to believe that only tc-id is needed in one place, and only "specification-id" in another. Please justify. Line 508 says "Form ONE (with the TC identified with the Product) should be deprecated." This suggests that perhaps "specification:[specification-id]" was mistakenly omitted from Form One. - p.17, line 512: RFC 3122 is titled "Extensions to IPv6 Neighbor Discovery", which is probably not an OASIS naming RFC. Also, Normative References does not include either [RFC 3121] or [RFC 3122] (or whatever the second should be). - p.18, line 578: append "other" to the specified path. - p.19, line 585: [version] should specify whether "v2.0" or "2.0", etc. is to be used for [version] here. I recommend "2.0" form. Anne -- Anne H. Anderson Email: Anne.Anderson@Sun.COM Sun Microsystems Laboratories 1 Network Drive,UBUR02-311 Tel: 781/442-0928 Burlington, MA 01803-0902 USA Fax: 781/442-1692
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]