HTML Review

[dblodgett-usgs]

Related to #248 -- @dazzasmith is working through a review. Further commits will show up in this pull request.

[dazzasmith]

A list of comments/questions concerning the HTML document for review. Note that I've not made an edit for these in the branch:

1. Just to check: I noticed that both 'data set'(s) (6) and 'dataset'(s) (37) are used throughout the document. Section 4: Terms and definitions mentions just 'data set' (4.13). Perhaps a need to add '(also dataset)' to 4.13 heading?

[dblodgett-usgs]

Good catch on dataset/data set. I've usually followed the logic ... "dataset for certain datasets; data set for any set of data in general" Not sure if I applied that logic here, but I'd also be happy to just auto correct everything to "data set" since "dataset" is kind of jargon. Opinion?

[dazzasmith]

Auto correct sounds fine, but be aware of the two cases where it's part of a reference that has it as 'dataset'. One of these I'm sure you're very familiar with :-)

• USGS National Hydrography Dataset Plus (NHD Plus)
• French National Service for Water Data and Reference-dataset Management (SANDRE)

[dblodgett-usgs]

This is the case where it's a (very) certain dataset. I may be inclined to leave it one word in all instances where it's referring to a named dataset.

[dazzasmith]

That sounds sensible, then there's a rule that's applied consistently. But it brings me back to my original question I guess, namely, should we add an explanation of these alternate forms to section 4.13?

[dblodgett-usgs]

Yeah... probably. Want to take a crack at that?

[dazzasmith]

Ok, will do. I'll be putting in a couple of hours later today, so I'll give it a go then.

[dazzasmith]

There seems to be some missing content for Table 1 (Note: that I've made a few other minor edits, punctuation etc., to the table on my branch). Column one of row three is empty in the HTML version and the latest word doc that I have?

[dazzasmith]

A possible clarification to add to the document: I can't remember how we got to the 0..1 Outflow cardinality for HY_HydroNexus in the role of outflow for an associated HY_Catchment, but reading the text 'Conceptually, each catchment has an outflow hydro nexus, and any hydro nexus has a corresponding catchment' the reader may well be confused to see the zero-to-one. Are we saying that a catchment doesn't have to have a conceptual outflow nexus? Don't we always need a nexus in order to define a catchment?

[dazzasmith]

@dblodgett-usgs @IrinaDornblut, I've got a couple of outstanding comments (see above). Also David, let me know if I need to speed things up. I'm doing a few quick edits each day that I get a seat on the train on my way to work (still finding things). I'm in the normative part of the doc at the moment.

[IrinaDornblut]

answering comments above:

1) "Column one of row three is empty in the HTML version and the latest word doc that I have?" -- this is correct (for me) since in HY_Features is no referencing method (feature type) specified. to explain that a method is still 'covered' by the abstract, interpolative or descriptive distance exporession names (in column two) a spearate row is included. -- maybe we should indicate the emoty field using '---', or so.

2) "0..1 Outflow cardinality for HY_HydroNexus in the role of outflow" -- 0..1 cardinality is used here to provide an opportunity to use the catchment hierarchy model in implementations where the (always logically existing) nexus is not known. -- If required, an implementation may specify it to 1..1.

[dazzasmith]

Thanks for your reply @IrinaDornblut.

1. IMHO I think it's best to add something to the empty cell in table 1 to avoid confusion, perhaps something like the following?

_<A referencing method (feature type) is not explicitly specified in HYFeatures>

2. I'd suggest that we add your text (refined slightly below), to clarify. I'll try and slot it in and then it can be verified along with all the other edits in my review.

_Note that, 0..1 cardinality is used for HYHydroNexus in the role of outflow to provide an opportunity to use the catchment hierarchy model in implementations where the (always logically existing) nexus is not known. If required, an implementation may specify it to be 1..1.

[dblodgett-usgs]

Sounds good. I think we have some time. The vote is set to close Oct 1 and I think we are on track to get quorum. We are at 29% of 33% now. After the vote we will likely need to finalize things pretty quickly, but I know there will be some time between that and when we need to have all of these minor editorial issues fixed. Thanks for taking the time!

[dazzasmith]

Thanks David, it all sounds good then. I'll shoot for wrapping things up by the end of the month.

[dazzasmith]

Just to check, in the following paragraph (7.3.3 paragraph 2), @dblodgett-usgs @IrinaDornblut:

The River Referencing system uses the one-dimensional topological realization of catchment within the implied hydrologic complex such that the feature to be placed and the already located referent are nodes on the boundary of the same flowpath.

Is this correct, namely that the feature to be placed is a node on the 'boundary' of the flowpath? When I picture this, the nodes on the boundary of the flowpath are nodes that are already located referents such as inflow and outflow nexuses, or perhaps a node that has already been placed (?). Thus, a feature that has not yet been placed wouldn't (yet) define the boundary of the flowpath right? Sorry if this is perhaps being a little pedantic.

[dblodgett-usgs]

In the case that the flowpath is to be split when placing the feature to be placed, this (both bodes on a boundary of a flowpath) would be correct. I prefer not to treat the splitting a flowpath case as the norm though. Want to suggest better wording? I don't know quite what the context of this sentence is.

[IrinaDornblut]

If the feature to be placed (hydro location) realizes a (existing or new) hydro nexus as a topological node, then it forms boundary on the flowpath edge. -- If the feature to be placed (hydro location) not realizes a hydro nexus as a topological node, it is located along that flowpath that has the reference location as a boundary.

Since the definition whether the feature to be placed forms a nexus (as topological node) will vary application-specific, I would like to avoid the terms ‘node’ and ‘boundary ‘ in this sentence (leaving the underlying definition to implementation). -- The following text then explains how this may work for a flowpath realizing a catchment between inflow and outflow nodes.

E.g., “The River Referencing system uses the one-dimensional topological realization of catchment within the implied hydrologic complex such that the feature to be placed and the reference location are on the same flowpath. Given that a flowpath ... ”

Makes sense?

[dazzasmith]

Thanks @dblodgett-usgs and @IrinaDornblut. I'll have a go at reworking Irina's new text into the section. However, I'm left a little unclear when you (Irina) say "...I would like to avoid the terms ‘node’ and ‘boundary‘ in this sentence (leaving the underlying definition to implementation)...", would you like me to attempt to replace them with alternatives?

[dazzasmith]

Another query. In the first paragraph under the heading 'Channel Network' (7.4.1) I'm wondering whether the second 'channel network' is correct, or should it perhaps have been something else (Hydrographic Network perhaps)? It just seems a little confusing to me:

...If the realized catchment is connected with other catchments via hydro nexuses, the channel network is considered connected to the channel network realizing these catchments.

[IrinaDornblut]

1) no replacment, only removing within a good wording. text proposal: " ... the feature to be placed and the reference location are [located] on the same flowpath ..."

2) "...If the realized catchment is connected with other catchments via hydro nexuses, the channel network is considered connected to the channel network realizing these catchments._ [meaning that the realizations of connected catchments are considered connected]

[dazzasmith]

@dblodgett-usgs I've addressed the two issues previously mentioned above and have now finished my review. However, I'm still playing around with Annex-C (AHGF) to try and improve things there. It's unlikely that I'll ever be totally satisfied, so just let me know when I need to stop :-)

[dblodgett-usgs]

👍 This is great. I've opened a few issues to follow up on this and there's one comment about a "nots" rather than "not" that I'm more curious about than anything.

[dazzasmith]

@dblodgett-usgs In my enthusiasm to wrap things up I'd forgotten that there were actually other annexes after the AHGF. So I've started reviewing them, shouldn't take long (most likely only missing punctuation etc.). I'll try and finish them off today. Sorry about that.

[dazzasmith]

@dblodgett-usgs I've now finished editing the remaining annexes (following Annex C). The edits are mainly minor and I've tried to refrain from changing anything that might change the intended meaning (unless it seemed clear). Feel free to reject any changes that seem questionable. As mentioned earlier, I'll continue with my tweaks to Annex C (AHGF) until you tell me to stop :-). But I will now not touch anything outside of said Annex.

[dblodgett-usgs]

Thanks!