[webauthn] Merged Pull Request: mmiller-improve-terminology

MasterKale has just merged MasterKale's pull request 1615 for https://github.com/w3c/webauthn:

== mmiller-improve-terminology ==
This PR is my effort to start a conversation on how the beginning of the spec might be reorganized to gradually introduce newcomers to the spec and establish specialized vocabulary before using it in the meat of the document. I've made the following changes:

1. **Use Cases** and **Sample API Usage Scenarios** were raised a header level
2. **Use Cases** now immediately follows **Introduction** to hook readers by demonstrating the capabilities of API with the existing straight-forward scenarios
3. **Dependencies** and **Terminology** follow **Use Cases** to define much of the specialized vocabulary that will be used throughout the rest of the document.
3. **Conformance** now comes after **Dependencies** and **Terminology** as it makes heavy use of vocabulary that is (now) defined beforehand.
4. **Sample API Usage Scenarios** is now the second-to-last section of the document, above **Acknowledgements**, so that everything before it describes "what WebAuthn is", then ends with "here is how you might practically use it".
5. I also fixed a bit of grammar, and a definition that used "attest" to describe "attestation" (you can't use a word to describe itself! 😂)

After all of this reorganization the document flows something like this:

- Introduction
- Specific Vocabulary
- Core Concepts
- Recommendations and Considerations
- Sample Usage

## Context

After an enlightening conversation earlier this week with @equalsJeffH, I came to understand that I've been misusing key terminology and causing confusion in some of my replies to issues, discussions in WG meetings, etc...

While I work on that, I started thinking back to _how_ I came to incorrectly use terms like "attestation" when I really meant "registration", or "assertion" when I really meant "authentication". I think part of it might have been how overwhelming the spec was as a newcomer. The **Terminology** section of the spec never really jumped out at me until recently (sorry @equalsJeffH 😅), and the spec is quick to start using vocabulary in the first couple of sections that aren't defined until a couple of sections later. This all got me thinking about how the spec might be better organized, so I took it as a chance to contribute to the spec in a material way.

I have a hunch this proposed reorganization might be way too drastic - as it's my first PR as a WAWG member I'm still feeling things out. Regardless of the fate of this PR I think there's an opportunity to improve the flow of the spec to benefit readers of all familiarity levels that's worth talking about.


<!--
    This comment and the below content is programatically generated.
    You may add a comma-separated list of anchors you'd like a
    direct link to below (e.g. #idl-serializers, #idl-sequence):

    Don't remove this comment or modify anything below this line.
    If you don't want a preview generated for this pull request,
    just replace the whole of this comment's content by "no preview"
    and remove what's below.
-->
***
<a href="https://pr-preview.s3.amazonaws.com/w3c/webauthn/pull/1615.html" title="Last updated on Jun 14, 2021, 6:33 PM UTC (6ab9d71)">Preview</a> | <a href="https://pr-preview.s3.amazonaws.com/w3c/webauthn/1615/ff7c715...6ab9d71.html" title="Last updated on Jun 14, 2021, 6:33 PM UTC (6ab9d71)">Diff</a>

See https://github.com/w3c/webauthn/pull/1615


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Wednesday, 16 June 2021 19:29:12 UTC