search

w3c-ccg / did-spec

Please see README.md for latest version being developed by W3C DID WG.
https://w3c.github.io/did-core/
Other
124 stars 45 forks source link

Some comments by Steven Rowat #267

Closed peacekeeper closed 5 years ago

peacekeeper commented 5 years ago

See https://lists.w3.org/Archives/Public/public-credentials/2019Aug/0047.html

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” ...

jandrieu commented 5 years ago

Closing because we've moved it to the DID WG did-spec repo. https://github.com/w3c/did-spec