Re: [emergency-adopt-docs] Comments on CAP Example Practices Document

Subject: Re: [emergency-adopt-docs] Comments on CAP Example Practices Document

On Tue, Jan 8, 2013 at 4:59 PM, Anthony Mancuso <amancuso@google.com> wrote:

EMA members, Elliot, and any other interested persons,

Yu Chen and I are working on a new version of the Example Practices: CAP Feeds doc (new title), which we will upload to the EMA-Collateral and Documents SC soon after we make changes in response to today's SC meeting. It will contain just the web feed portions of the larger doc we have been developing.

I started a Example Practices: CAP Elements doc, which has the CAP element portions of the previous doc. I edited it in response to Elliot Christian's past and latest comments plus our discussion at the SC meeting today. Since we don't have template approval for this second doc, it is unofficial, but I wanted anyone interested to see it and make any comments they feel appropriate.

The first (unofficial) draft of the CAP Elements doc is attached.

Thanks,

Tony

On Mon, Jan 7, 2013 at 3:17 PM, Elysa Jones <elysajones@yahoo.com> wrote:

Friends,

Eliot Christian a CAP subject matter expert was asked to review and comment on the CAP Example Practices Document during the subcommittee drafting of the document. He provided edits to Tony’s version and this was reviewed with several members on a call today (Yu, Tony, Gary Ham, Eliot, Elysa). The comments were well received and all agreed the discussion should continue on the regular Collateral and Documents SC call 1/8.

It should be noted that Eliot is not an OASIS member but is commenting as a subject matter expert. He will be attending the call in that same capacity. He understands that anything he provides is a free contribution with no encumbrances from an IP standpoint.

There are five additional items Eliot would like the SC to consider adding to the document as follows: free-form text is more useful if you do it this way:

The <description> and <instruction> elements allow for free-form text. The text should be structured, legible, relevant, and useful for the audience in the alert area. Instruction text is best when it is also actionable.
Structured text allows different CAP clients to parse the text for their own use more easily.



NWS follows a formulaic (not structured) format

For Example Practices: Cap Elements (copy over from old doc with comments see Eliot's file.)

(1) Urgency, Severity, and Certainty - Every CAP alert SHOULD
have values other than "Unknown" for Urgency, Severity, and

Certainty. In practice, it appears that CAP implementations
treat "Unknown" as "insignificant". So, a CAP alert could
be ignored if the value "Unknown" occurs in these elements.



(2) The terms "Advisory, Watch, Warning" are not used consistently
across hazard types with respect to the separate CAP aspects

of Urgency, Severity, and Certainty. Given that NWS is currently
considering revisions (see http://nws.weather.gov/haz_simp/ ),

now may not be a good time to discuss good practice for these.
Avoid good practice on above.
(3) Geographic location - In ATOM and RSS, I suggest including

the cap:area element with its sub elements exactly as coded in the
actual alert (e.g., see http://www-db.wmo.int/alerting/atom.xml

and http://www-db.wmo.int/alerting/rss.xml )
put these in both Atom and RSS; good practice to have practice in feed, but also give them CAP file link. Put this in feed doc.

(4) Geographic Precision - Discuss the widespread misapplication
of overly precise coordinate values, often far beyond realistic
accuracy. (CAP 1.0 contained a "Coordinate Precision" Note but
it was dropped in 1.1, apparently by an editing error?). Also,
the use of zero for a circle radius should be discouraged as it

implies a geometric point but in reality should be comparable in
scale to the precision implied by the circle center coordinates.
don't need too much precision; have it related to actual accuracy;

(5) Other Geographic Notes - Perhaps discuss closure of a polygon,
winding order of polygon coordinates, and validating polygons?
Aside: Is there a note on how best to indicate the whole earth

(e.g., for many space weather hazard threats).

Eliot Christian a CAP subject matter expert was asked to review and comment on the CAP Example Practices Document during the subcommittee drafting of the document. He provided edits to Tony’s version and this was reviewed with several members on a call today (Yu, Tony, Gary Ham, Eliot, Elysa). The comments were well received and all agreed the discussion should continue on the regular Collateral and Documents SC call 1/8.

It should be noted that Eliot is not an OASIS member but is commenting as a subject matter expert. He will be attending the call in that same capacity. He understands that anything he provides is a free contribution with no encumbrances from an IP standpoint.

There are five additional items Eliot would like the SC to consider adding to the document as follows: free-form text is more useful if you do it this way:

The <description> and <instruction> elements allow for free-form text. The text should be structured, legible, relevant, and useful for the audience in the alert area. Instruction text is best when it is also actionable.

Structured text allows different CAP clients to parse the text for their own use more easily.

NWS follows a formulaic (not structured) format

For Example Practices: Cap Elements (copy over from old doc with comments see Eliot's file.)

(1) Urgency, Severity, and Certainty - Every CAP alert SHOULD

have values other than "Unknown" for Urgency, Severity, and

Certainty. In practice, it appears that CAP implementations

treat "Unknown" as "insignificant". So, a CAP alert could

be ignored if the value "Unknown" occurs in these elements.



(2) The terms "Advisory, Watch, Warning" are not used consistently

across hazard types with respect to the separate CAP aspects

of Urgency, Severity, and Certainty. Given that NWS is currently

considering revisions (see http://nws.weather.gov/haz_simp/ ),

now may not be a good time to discuss good practice for these.

Avoid good practice on above.

(3) Geographic location - In ATOM and RSS, I suggest including

the cap:area element with its sub elements exactly as coded in the

actual alert (e.g., see http://www-db.wmo.int/alerting/atom.xml

and http://www-db.wmo.int/alerting/rss.xml )

put these in both Atom and RSS; good practice to have practice in feed, but also give them CAP file link. Put this in feed doc.

(4) Geographic Precision - Discuss the widespread misapplication

of overly precise coordinate values, often far beyond realistic

accuracy. (CAP 1.0 contained a "Coordinate Precision" Note but

it was dropped in 1.1, apparently by an editing error?). Also,

the use of zero for a circle radius should be discouraged as it

implies a geometric point but in reality should be comparable in

scale to the precision implied by the circle center coordinates.

don't need too much precision; have it related to actual accuracy;

(5) Other Geographic Notes - Perhaps discuss closure of a polygon,

winding order of polygon coordinates, and validating polygons?

Aside: Is there a note on how best to indicate the whole earth

(e.g., for many space weather hazard threats).

How many points do you need; windy river need thousands of points for county boundary; we don't need that for CAP; scale of a kilometer or so are probably not necessary; (30 points instead of 30)

point people to functions that exist to simplifying polygons. There is a profile of a GML simple features (simple syntax) profile that simplified the use of for CAP 2.0. Add a precision note from that effort.

We will see you all on the call tomorrow.

How many points do you need; windy river need thousands of points for county boundary; we don't need that for CAP; scale of a kilometer or so are probably not necessary; (30 points instead of 30)

point people to functions that exist to simplifying polygons. There is a profile of a GML simple features (simple syntax) profile that simplified the use of for CAP 2.0. Add a precision note from that effort.

We will see you all on the call tomorrow.

Elysa

emergency-adopt-docs message