Re: Created DID Spec Final Community Group Report

On 2019-08-10 2:02 pm, Markus Sabadello wrote:
...> 1. Created a static copy of the DID Spec Final Community Group 
Report
> here:
> https://w3c-ccg.github.io/did-spec/CGFR/2019-08-10/
...
> In that case, I think the next step is for everyone to review, and for 
> the W3C CCG Chairs to publish the CGFR.
> 
> Markus

Greetings,
and my comments on the above CGFR DIDs v0.13 page:

Great work!
Overall seems fully comprehensible.

Only three niggles that slowed/confused my reading:


In Section “4.7 Fragment”:

Is the following possibly meant as an Issue, that should be in pink 
background? :

“It is desirable that we enable tree-based…”

If not, I think it should be recast into the passive voice, since the 
use of “we” is unsettling; before this point I believe all grammar has 
been in the passive voice (except for one previous pink “Issue” that 
contains “we”).

Plus that sentence “It is desirable that we…” is long and convoluted 
and I find it difficult to follow, so maybe best if it is also recast 
into two or more sentences?


In Section “5.10 Extensibility”:

— Uses “we" and "us”; again different from the rest of the document.
— Less terse writing than the rest of the document to this point; more 
like a marketing section; ie., uses what appear to be strictly 
unnecessary phrases like “a simple matter of” and “developers are 
urged to”.

I believe it would be more in keeping with the rest if this section 
was rewritten slightly more tightly, and fully passive voice.


In Section “6.2 JSON-LD”:

— I believe the term “syntactic sugars” is unnecessarily rare (I had 
to look it up) for the widest possible readership. It also seems 
unnecessary given the explanation of the paragraph it is set in. I 
suggest changing to:
“The most noteworthy [of these] provided by JSON-LD are:...”


Plus niggling niggle:

in Section 2
Period missing after “...previous transaction” ...


That’s all… :-)

Steven

Received on Sunday, 11 August 2019 18:48:29 UTC