Did-core: Uses of terms defined in the specification should be links to their definitions

[selfissued]

There are gobs of uses of identifiers in the spec that are rendered in red fixed-width font but that are not hyperlinks to the definitions of the terms. For instance, Section 3.3 https://w3c.github.io/did-core/#cryptographic-keys-and-other-verification-methods contains uses of the identifiers publicKey, authentication, id, type, and controller, that do not link to their definitions, such as Section 6.3 https://w3c.github.io/did-core/#public-keys for publicKey.

Please make every use of a term defined in the specification a hyperlink to the definition. (This change will be purely editorial.)

[selfissued]

@talltree volunteered on the 10-Mar-20 call to do this.

[talltree]

On the 2020-03-12 call, the editors discussed this and decided to divide it into two tasks.

The first is the semantic verification of terminology usage throughout the document. That task we need to do anyway as part of our work on section 2, Terminology, so we will proceed with that, with myself on point for that for the editor's team.

The second task is the hyperlinking of terms with Respec tags. This has some logistical challenges because:

1. We confirmed that hyperlinking a term that is a property name—that would otherwise be in a fixed width orange font—will turn it into a blue underlined term that looks like a glossary entry. So we need to decide about whether that tradeoff is worth it.
2. Trying to do all the Respec glossary entry tagging early in the process means it becomes a requirement that all PR authors know how to do this and apply it uniformly. So it may be best to wait until an opportune point, such as just before CR, to add these Respec tags throughout the document.

[rhiaro]

When referring to property names, I propose keeping them as fixed width (<code>) formatted for readability, and to be clear that we are specifically referring to data model property names, not related general concepts. Eg. talking about public keys in the DID spec is different to talking about publicKey in the DID document.

To address this issue, when a property name has its own section, we can link to that after the first occurrence of the fixed width reference per section, not including when the property name appears in its own explanatory section. Eg.

Regarding cryptographic key material, public keys can be included in a DID document using, for example, the publicKey or authentication (see Section 7.4 Authentication) properties, depending on what they are to be used for.

There's nothing we can really link the id and type properties to. They tend to be defined in the section in which they are mentioned, since the values or conformance requirements may be different depending on what type of object they are part of.

[OR13]

This seems like a thing to do at the very end, if ever.

[msporny]

This is purely editorial... which means, we'll do this right before we go to CR.

[burnburn]

But if anyone has opinions to share, please do so now.

[iherman]

respec has some tools to help you on this

[rhiaro]

Would any editors have any objection to agreeing that we link the terms only the first time they appear in a paragraph? It seems a bit excessive to link every term every single time, and some paragraphs are so jammed with links it's odd to read in my opinion.

[burnburn]

Although I’m not an editor on this spec, having done this myself on many
specs I never found it difficult to do or to read. It’s no different from
putting all computer code in fixed-width font, or many other common
conventions in technical publications. And search and replace works
wonders if you confirm each before replacing :)

It can be difficult to maintain, however, while the document is changing
rapidly. Maybe you can just link the first occurrence in each paragraph
now and then someone can fill in at CR. Right now we just need a barely
passable doc for our initial horizontal review.

On Tue, May 19, 2020 at 2:21 AM Amy Guy [e-mail] wrote:

Would any editors have any objection to agreeing that we link the terms
only the first time they appear in a paragraph? It seems a bit excessive to
link every term every single time, and some paragraphs are so jammed with
links it's odd to read in my opinion.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/w3c/did-core/issues/163#issuecomment-630608545, or
unsubscribe
https://github.com/notifications/unsubscribe-auth/AAI54UZ33UQJ7BVVQL66DBLRSIQPBANCNFSM4KODQZ2Q
.

[msporny]

Would any editors have any objection to agreeing that we link the terms only the first time they appear in a paragraph?

I've attempted this on just about every spec and have only been successful once. There is always someone that comes along and insists that you didn't mean to use a word because it's not highlighted and to change that word to something else... because, the word you used is clearly a special word and it would have been marked as such had you used it appropriately. Other times, people complain that they skimmed and missed the fact that the word being used had special meaning in the specification.

Yes, this approach turns reading the spec into a bit of a gazing into a christmas tree exercise, but I think the benefits outweigh the drawbacks. I do find it useful when reading to click on a word in a sentence after passing by in a few times in previous sentences to read it's exact definition... it's lazy, yes, but if it's highlighted you can be sure of it's definition instead of not knowing if the Editors really meant to use the word in the way they did in a particular sentence.

All that to say, I think we should highlight every special term in the spec. If it's hard to read, we may want to rethink what the markup is for special words so it's easier on the eyes.

[rhiaro]

xD fair enough, I'll do them all, but yeah I'll wait til the end when edits have slowed down a bit

[talltree]

We discussed this issue again on the 2020-06-16 WG call. It was agreed that the editors and PR submitters should try to tag all terms as they can, but that we will wait to do a final pass on linking all terms until we are just before CR.

[msporny]

We will tag all terms right before going to CR.

[msporny]

PR #573 addresses this issue. This issue will be closed once PR #573 is merged.