[Requests] Comments on 08-131r2 "The Specification Model - Modular specifications"

Walker, Stewart A (US SSA) stewart.walker2 at baesystems.com
Sun Apr 12 00:28:29 EDT 2009


All,

 

We (Stewart Walker and Arliss Whiteside) provide comments on OGC
document 08-131r2, with the title "The Specification Model - Modular
specifications".  We use a modification of the standard OGC format for
comments on RFP-proposed OGC Implementation Specifications.

 

As representatives of a company developing geospatial systems that use
OGC standards, we agree with this proposal to improve the requirements
and tests specified by OGC standards.  We are NOT trying to delay this
activity more than necessary.  We are trying to prompt the OGC to spend
more effort now, before approval of this new standard, on the
improvements required to make this standard useful and applied.

 

Many of our comments are editorial, but even these are examples of major
comment B below, that the current document is too difficult to
understand.  We do not believe that final editing of this document via
the usual OGC process will correct enough of these issues to make this
document sufficiently easy to understand, by current and prospective
authors and editors of OGC standards: we recommend more extensive
redrafting.

 

 

PART A

 

1. Evaluators:

Stewart Walker

BAE Systems

Stewart.Walker at baesystems.com

 

Arliss Whiteside

BAE Systems

Arliss.Whiteside at baesystems.com

 

2. Document: OGC 08-131r2 "The Specification Model - Modular
specifications"

 

PART B

 

A.1. Document Clauses: General

2. Criticality: Major

3. Current text: General

4. Comments/justifications for changes:  It is not clear how many of the
stated requirements can be satisfied by future OGC standards, and
whether satisfying many of the stated requirements is fully practical.
We request the inclusion of extensive illustrations of how to satisfy
the stated requirements, by giving examples of specifying requirements
and tests in subject standards which would meet the stated requirements.

 

B.1. Document Clauses: General

2. Criticality: Major

3. Current text: General

4. Comments/justifications for changes:  The text in this document is
extremely hard to understand, by current and prospective authors and
editors of OGC standards.  We believe that the understandability of this
document must be substantially improved before OGC standards are
expected to comply with the stated requirements.  In addition to the
comment A above, most of the editorial comments below concern points
where the current text is hard to understand.

 

C.1. Document Clause: Annex A

2. Criticality: Major

3. Current text: Annex A

4. Comments/justifications for changes: It is not clear how to state
performance tests in the Abstract Test Suite of a subject standard.  We
assume that the Compliance Test Language (CTL) now specified in OGC
06-126r2 is NOT suitable or recommended.  Are the tests stated in Annex
A of this document recommended as examples for Abstract Test Suites in
subject standards?  We request that this document specifically reference
or include examples of how performance tests should be stated in
Abstract Test Suites of subject standards.

 

D.1. Document Clause: General

2. Criticality: Editorial

3. Current text: The word "associated" is often followed by "to", not by
"with".

4. Comments/justifications for changes: Are all these associations "to"
one-way (does this mean navigable?)?  We believe that the more common
phrase is "associated with".  We suggest that the most current uses of
the phrase "associated to" be changed to be followed by "associated
with".

 

E.1. Document Clause: General

2. Criticality: Editorial

3. Current text: The term "requirements class" is defined, but the term
"requirement classes" is often used to refer to multiple classes of
requirements.

4. Comments/justifications for changes:  This difference between single
and multiple terms is often hard to understand.  We suggest that the all
occurrences of "requirement classes" be changed to "requirements
classes".

 

F.1 Document Clause: Introduction

2. Criticality: Editorial 

3. Current text: "A standard's usefulness and hence worth can be
measured by:"

4 Comments/justifications for changes: The quoted sentence contains the
useless phrase "and hence worth".  We suggest that this phrase be
deleted, so that this sentence reads "A standard's usefulness can be
measured by:"

 

G.1 Document Clause: Introduction

2. Criticality: Editorial 

3. Current text: "This standard specifies generic rules for this
internal structure conducive to being a true RUE (really useful
engine)."

4 Comments/justifications for changes: The quoted sentence may be witty,
but it contains an acronym that is not used again.  We suggest that this
sentence be simplified to read "This standard specifies generic rules
for this internal structure conducive to being a true Really Useful
Engine."

 

H.1 Document Clause: Introduction

2. Criticality: Editorial 

3. Current text: "Thus, a standard presents requirements targeting
implementations of solutions of the original problem, which must be
satisfied the tests of the conformance suite."

4 Comments/justifications for changes: The quoted sentence is hard to
understand, and is not complete.  We suggest that this sentence be
edited to read "Thus, a standard presents requirements on
implementations of solutions. These requirements must be satisfied by
performing the tests of the defined conformance suite."

 

I.1 Document Clause: 1

2. Criticality: Editorial 

3. Current text: "Clause 6.1 contains the model of a standard upon which
this standard is described."

4 Comments/justifications for changes: The expression "the model of a
standard upon which this standard is described" is hard to understand.
We suggest editing this sentence to avoid twice using the word
"standard".

 

J.1 Document Clause: 1

2. Criticality: Editorial 

3. Current text: "These two sections can be read first to aid in the
understanding of the rest of the document."

4 Comments/justifications for changes: The sentence seems to be too
wordy for easiest understanding.  We suggest editing this sentence to
read "These two sections can be read first to help understanding the
rest of the document."

 

K.1. Document Clauses: 2

2. Criticality: Editorial

3. Current text: "2 The reference to the OGC TC PnP is floating, and
does not apply to a particular document, but to the policy and
procedures of the Open Geospatial Consortium whether defined by an OGC
document, by Roberts Rules of Order, or by common consent and practice
of the membership. The status of this standard in the OGC Policy and
Procedures must be found in that document. This requirement is for that
document and is not a requirement of this one."

4. Comments/justifications for changes:  This footnote is very hard to
understand.  It uses both "OGC TC PnP" and "OGC Policy and Procedures",
which both differ from "OGC TC Policy and Procedures" in the body.  Then
it states that the reference does not apply to a particular document -
this is OK - but two lines later we say, "... must be found in that
document". The final sentence, "This requirement is for that document
and is not a requirement of this one," is opaque.  "Roberts" should have
an apostrophe.  Perhaps "Roberts Rules of Order" should be italicized. 

 

L.1. Document Clauses: 2

2. Criticality: Editorial

3. Current text: "Numbered clauses in this standard contain normative
language and thus place requirements on conformance or mechanism for
adoption of candidate standards to which this standard applies."

4. Comments/justifications for changes:  What does the phrase "or
mechanism" mean here?  Does it add anything to this sentence?  Does this
sentence apply to all numbered clauses?  We suggest simplifying this
sentence to read "Numbered requirements in this standard are normative
and thus place requirements on conformance for adoption of candidate
standards to which this standard is applied."

 

M.1. Document Clauses: 3

2. Criticality: Editorial

3. Current text: "While this document references UML, SQL and XML, and
their technical specification, it does not derive any of its
requirements from these documents."

4. Comments/justifications for changes:  The multiplicity of the word
"specification" is wrong in this sentence.  We suggest replacing the
word "specification" with the word "specifications" in this sentence.

 

N.1. Document Clauses: 4.18

2. Criticality: Editorial

3. Current text: "A data specification requires data structures, but a
procedural specification required software implementations."

4. Comments/justifications for changes:  The word "required" is
incorrect in the second part of this sentence.  We suggest replacing the
word "required" with the word "requires" in this sentence.

 

O.1. Document Clauses: 4.22

2. Criticality: Editorial

3. Current text: "Standard and specification can apply to the same
document, while specification is always valid, standard really only
applies after the adoption of the document by a standards organization."

4. Comments/justifications for changes:  The punctuation in this
sentence seems incorrect.  We suggest editing this sentence to read
"Standard and specification can apply to the same document. However,
while specification is always valid, standard only applies after
adoption of the document by a standards organization."

 

P.1. Document Clauses: 4.24

2. Criticality: Editorial

3. Current text: "In general, the types inherit from one another in the
same was that UML classes do."

4. Comments/justifications for changes:  This is not a correct sentence,
probably because it reads "was" instead of "way". We suggest editing
this sentence to replace "was" with "way".

 

Q.1. Document Clauses: 5.2

2. Criticality: Editorial

3. Current text: "UML 2 (Unified Modeling Language as defined by OMG and
accepted as a PAS (publicly available standard) by ISO)"

4. Comments/justifications for changes:  The quoted sentence contains
nested quotation marks plus an acronym that is not used again.  We
suggest that this sentence be simplified to read "UML 2 (Unified
Modeling Language as defined by OMG and accepted by ISO as a publicly
available standard)"

 

R.1. Document Clauses: 5.2

2. Criticality: Editorial

3. Current text: Does not include acronyms TC and SQL

4. Comments/justifications for changes:  We suggest that the acronyms TC
and SQL, which are each used multiple times in this document, be added
to this list of abbreviations and acronyms, and that the acronym RUE be
deleted (unless it is used twice).

 

S.1. Document Clauses: 5.3

2. Criticality: Editorial

3. Current text: "Recommendations are not tested and are not labeled,
although they still use a bold underlined font for their unique home
statement."

4. Comments/justifications for changes:  The word "underlined" seems
incorrect here. We suggest that this sentence be corrected to read
"Recommendations are not tested and are not labeled, although they still
use a bold font for their unique home statement."

 

T.1. Document Clauses: 6.1

2. Criticality: Editorial

3. Current text: "The precise enforcement of this requirements and its
associated recommendations is the purview of the OGC URI/URN Naming
Authority or its equivalence."

4. Comments/justifications for changes:  The word "requirements" seems
to have the wrong multiplicity here. Also, there is an OGC Naming
Authority, which deals only with URNs, not with other forms of URIs.  We
suggest that this sentence be corrected to read "The precise enforcement
of this requirement and its associated recommendations is the purview of
the OGC Naming Authority or its equivalent."

 

U.1. Document Clauses: 6.1

2. Criticality: Editorial

3. Current text: "This means that any failure to pass the test specified
for any part of requirement is a failure to pass the requirement and any
module or class that the requirement is contained in."

4. Comments/justifications for changes:  The sentence is hard to
understand, partially due to the closing phrase "that the requirement is
contained in".  We suggest that this sentence be improved to read "This
means that any failure to pass a test specified for a part of a
requirement is a failure to pass the requirement, and failure to pass
any module or class that contains this requirement."

 

V.1. Document Clauses: 6.1

2. Criticality: Editorial

3. Current text: "3 In this standard, in informative sections, the words
"will" imply that something is an implication of a requirement. The
"will" statements are not requirements, but explain the consequence of
requirements."

4. Comments/justifications for changes:  This footnote is hard to
understand, partially due to the word "words" and "imply" having the
wrong multiplicitly.  Also, the word "will" can be used in clauses which
include normative text.  We suggest that this sentence be improved to
read "3 In this standard, the word "will" is used when something is an
implication of a requirement. These "will" statements are not
requirements, but state the consequences of requirements."

 

W.1. Document Clauses: 6.1

2. Criticality: Editorial

3. Current text: "So, this standard defines a "requirements class" as a
set of requirements that must be all passed to achieve a particular
conformance class (see 4.5)."

4. Comments/justifications for changes:  This phrase "be all" in this
sentence seems backward.  We suggest that this sentence be improved to
read "So, this standard defines a "requirements class" as a set of
requirements that must all be passed to achieve a particular conformance
class (see 4.5)."

 

X.1. Document Clauses: 6.1

2. Criticality: Editorial

3. Current text: "How a particular request-response pair uses the data
structure to mean the title of a particular document or dataset, will be
specified in the requirements class in which the request-response pair
is defined and set against requirements."

4. Comments/justifications for changes:  This is not a complete correct
sentence, due to the included comma.  Also, what is meant by "set
against requirements"?  We suggest that this sentence be improved to
read "How a particular request-response pair uses a data structure will
be specified in the requirements class in which the request-response
pair is defined with its requirements."

 

Y.1. Document Clauses: 6.2

2. Criticality: Editorial

3. Current text: "5 This "test suite" specification is a requirement for
ISO and for OGC, but is often ignored in less formal standardization
efforts. In such cases, if there exist a "validation authority" for
conformance, they must interpret the requirements to be tested, ex
parte, possibly separated from the authors of the standard, leading to
issues of separate interpretations of the same specification."

4. Comments/justifications for changes:  This footnote is very hard to
understand, partially due to the incorrect multiplicity of "exist" and
"they".  We suggest that this footnote be improved and simplified to
read "5 This "test suite" specification is a requirement for ISO and OGC
standards, but is often ignored in less formal efforts. In such cases,
if there is a "validation authority" for conformance, it must interpret
the requirements to be tested, often separated from the authors, leading
to multiple interpretations of the same specification."

 

Z.1. Document Clauses: 6.2

2. Criticality: Editorial

3. Current text: "For example, in a service interface, a specification
may be written that require both the client and server to use a
particular language for data transmission."

4. Comments/justifications for changes:  This footnote is hard to
understand, partially due to the incorrect multiplicity of "require".
We suggest that this sentence be improved and simplified to read "For
example, in a service interface, a specification may be written that
requires both clients and servers to use a particular language for data
transmission."

 

AA.1. Document Clauses: 6.2

2. Criticality: Editorial

3. Current text: "Since the client and server are likely different
standardization targets (except in some special circumstances), they may
have different conformance test classes."

4. Comments/justifications for changes:  This footnote is hard to
understand, partially due to phrase "likely different".  We suggest that
this sentence be improved and simplified to read "Since clients and
servers are different standardization targets (except in some special
circumstances), they may have different conformance test classes."

 

BB.1. Document Clauses: 6.3

2. Criticality: Editorial

3. Current text: "Req 7   The requirement structure of the document
shall be in a logical correspondence to the test suite structure."

4. Comments/justifications for changes:  This requirement is hard to
understand, partially due to phrase "requirement structure".  What is a
structure with only one requirement?  We suggest that this sentence be
improved to read "Req 7   The requirements structure of the document
shall correspond to the test suite structure."

 


CC.1 Document Clause: A.1.11 and A.1.12

2. Criticality: Editorial 

3. Current text: "A.1.11 Conformance class tests only one requirements
class"

and "A.1.12 Conformance class tests only one requirements class"

4 Comments/justifications for changes: These two clauses currently have
the same title.  We assume that one of these titles is incorrect, and
thus should be corrected.

 

 

We could go on and on, pointing out specific places where the current
wording seems incorrect or too hard to understand.  Many more such
places are listed in the attachment to this document.  This list also
includes places where we noticed errors in the formatting of this
document.

 

We hope that these comments will be construed in the constructive way in
which they were prepared, leading to an easier to read and more widely
used document.

 

 

Stewart Walker and Arliss Whiteside

 

 

 

 

Best wishes,

Dr. A. Stewart Walker
BAE Systems
Mail Zone 62-TAL
10920 Technology Place
San Diego
CA 92127-1874
USA

tel +1 858 592 1764
fax +1 858 592 5309
e-mail stewart.walker2 at baesystems.com
www.baesystems.com/gxp 

--------------------------------------------------

 

REGISTER NOW!! 

2009 BAE Systems GXP International User Conference and Professional
Exchange

May 4 - 8 2009 >> Hilton La Jolla Torrey Pines: San Diego, California.
Join us in May to see new software developments, technology R&D, and to
collaborate with industry peers. Technical program highlights include
eXtreme Analysis(tm) workflows for SOCET GXP(r) v3.1, a preview of SOCET
GXP v4.0, and SOCET SET(r) v5.5 enhancements: frame sensor model, new
sensors, and terrain tools. Click here for conference details
<http://www.socetgxp.com/content/?p=962> .

--------------------------------------------------

SOCET SET(r), VITec(r) and SOCET GXP are commercial software products
subject to U.S. Export Licensing Regulations. The export or re-export of
this software is governed by the Export Administration Regulations (EAR)
and/or the International Traffic in Arms Regulations (ITAR) of the
United States. This software may not be transferred to a non-U.S.
person/entity without the proper prior authorization of the U.S.
Government. Violations may result in administrative, civil or criminal
penalties.

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.opengeospatial.org/pipermail/requests/attachments/20090411/7ebd01bb/attachment-0001.htm 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: More Comments on OGC 08-131r2 v2.doc
Type: application/msword
Size: 147456 bytes
Desc: More Comments on OGC 08-131r2 v2.doc
Url : http://lists.opengeospatial.org/pipermail/requests/attachments/20090411/7ebd01bb/attachment-0001.doc 


More information about the Requests mailing list