Can we shift or somehow de-emphasize the terminology section?
dhh1128 opened this issue · 4 comments
I just sat down to read the specification as true HTML after a long time being down in the details, and I found myself feeling put off by the terminology section.
This is NOT because terminology isn't good, or needed. I know that a lot of work has gone into getting it into its present state, and I don't really want to change its content. I also understand that careful definitions are the foundation of clear communication. However, as a reader, I found myself taking the perspective of someone encountering many of the ideas in this DID method for the first time, and I found that running into technical definitions (beginning with ACDC, autonomic identifier, and CESR) before I encountered the overview material (how to recognize a DID in this method, how this method stores DID docs and supports CRUD operations) was confusing. I think it could also backfire, politically. We will have readers who come from a did:web background, and who need to feel this method's similarity to those concepts that they know; instead, we throw them into very deep water and overwhelm them with dense, unfamiliar, low-level details before they get the high-level concepts.
What I'm wondering is if we can find a way to bring the reader to the high-level concepts first, before they see glossary-like material. For example:
Option 1: Move terminology into an appendix.
I know it is common to put terminology up front, and that some standards orgs require this. DID Core has a terminology section before the heart of the spec. However, all uses of terminology are always hyperlinked, and we can even provide hovertext, so a term is never really used without providing its formal definition. Given that, the classic approach of defining terms first seems unnecessary.
Option 2: Do what is done in RFC 9110, which is to create a section called "Terminology and Core Concepts".
If you read that RFC thoughtfully, you will see that the section doesn't attempt to define every term/concept; it truly defines only the core ones. And it doesn't do so with a glossary; it does so through exposition. It is teaching, not just providing a reference. In our spec, "ACDC" is a supporting idea rather than a core concept, but because we have a generic terminology section, and because it sorts first alphabetically, and because we are defining rather than teaching in a broader sense, we run into this definition first. If we had a "Terminology and Core Concepts" section, we'd teach the core concepts, and introduce the terminology as we did so. We would still need a glossary, and the glossary would need to include more terms than we introduce in this section, but the basics could be learned from the exposition. (Of course, a drawback of this approach is that it takes a lot of editing. Maybe it's too ambitious.)
Option 3: Just put a disclaimer at the top of the Terminology section.
Recognizing how our terminology breaks up the flow for certain readers, we could simply insert a small statement at the front of it: "Careful definitions are foundational to a full understanding of this specification, and it's traditional to include them at the front of a specification. We provide them here. However, many readers may find it easier to skip ahead to the Core Characteristics section, and learn terms as they encounter them in context."
Great forest through the trees issue @dhh1128 I will take a look today and see which option(s) are needed.
I agree the terminology section transitioned to become our appendix. And we have been much more focused on it supplying nice hover over summaries and links for learning more. As such, we have enriched the whole document (all the refs) with this very useful functionality for the reader. As such I believe that the first option is appropriate (and simple), i will submit a PR that makes the terminology an appendix section.
I am working on a PR that hopefully begins to address this item. should be in today - but it is just a start. I am taking a few terms from the current ToIP Glossary, removing some extraneous and non-normative references. It'll be an exemplar, not a complete solution.