W3C home > Mailing lists > Public > public-webauthn@w3.org > May 2021

[webauthn] Pull Request: mmiller-improve-terminology-and-progression

From: Matthew Miller via GitHub <sysbot+gh@w3.org>
Date: Fri, 21 May 2021 05:45:35 +0000
To: public-webauthn@w3.org
Message-ID: <pull_request.opened-649672028-1621575933-sysbot+gh@w3.org>
MasterKale has just submitted a new pull request for https://github.com/w3c/webauthn:

== mmiller-improve-terminology-and-progression ==
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.

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 Friday, 21 May 2021 05:45:37 UTC

This archive was generated by hypermail 2.4.0 : Tuesday, 5 July 2022 07:26:43 UTC