search

w3c / webpayments-ig

Web Payments Interest Group
22 stars 29 forks source link

Add some terminology from the working group. #41

Closed tommythorsen closed 8 years ago

tommythorsen commented 8 years ago

I originally added these changes to master as PR https://github.com/w3c/webpayments-ig/pull/39, but that was probably the wrong branch, so here are the same changes for gh-pages.

adrianhopebailie commented 8 years ago

@halindrome, @msporny can we merge this PR?

halindrome commented 8 years ago

LGTM. I note that the lt attribute is actually deprecated in favor of data-lt. If you wanted to do a global change from lt=" to data-lt=" I wouldn't object.

msporny commented 8 years ago

@halindrome, @msporny can we merge this PR?

Hmm, don't think Shane nor I should be in the critical path for the WPIG glossary. My understanding was that all of the WPWG spec editors would manage the glossary together. So, what happened in this issue shouldn't happen in the future. Don't wait for Shane nor I to merge needed glossary changes, just go ahead and do it.

The glossary is in shambles, it never got out of "experimental" mode and is a grab bag of definitions from a bunch of different people. Editors, you're not going to hurt it by putting new definitions in as long as you don't stomp on other editors (which is, unfortunately, fairly easy to do).

Let's just iterate rapidly and use complaints from editors to fine tune the glossary. That will ensure that we put out the high priority fires first.

msporny commented 8 years ago

Hey @tommythorsen - thanks for the PR, I've merged it and made a number of fixes/updates to fix the other specs (that I know of) that the PR broke.

Here's why I pulled in the PR:

I'd like everyone to start using common terminology across all the Web Payments specs. Rather than nitpick the terms, let's get them in there, get everyone using the same terminology document, and then refine the glossary language over time.

Here's what I don't like about the PR:

The Web Payments Core Messages spec only had a handful (3-5?) terms before the PR. It now pulls in 27 terms, which is off-putting for people reading what is supposed to be a fairly simple spec (from a conceptual standpoint):

https://w3c.github.io/webpayments-core-messages/#terminology

The reason it pulled in all of those terms is because your PR cross-references a ton of the terms, so you pull in one of them and you pull in the 20 that are linked to that simple term. We need to make sure that we're cross-referencing only when it makes sense to do so and understanding that when we do, we pull in the entire graph of terms linked to the original term.

Some of this may be due to a bug in ReSpec's terminology linking code, but the rest may be because we're defining too many terms that are far too similar. For example: Displayed payment app, browser-based payment app, enabled payment app, ignored payment app, invoked payment app, matching payment app... each one of those things doesn't need to be defined in the glossary. I'd argue that some of those are "states" of payment apps.

So, all this to say that we really need to fix this massive amount of terminology being sucked into specs that don't use the terminology at all:

https://w3c.github.io/webpayments-core-messages/#terminology

@halindrome - any thoughts on debugging why certain terms are being pulled in? For example, I know that "browser-based payment app" isn't referenced anywhere in the link above, but it shows up in the glossary. That said, I also know that other terms that are not referenced are being cleaned out of the terminology section. So, part of this is a bug?

halindrome commented 8 years ago

@halindrome - any thoughts on debugging why certain terms are being pulled in? For example, I know that "browser-based payment app" isn't referenced anywhere in the link above, but it shows up in the glossary. That said, I also know that other terms that are not referenced are being cleaned out of the terminology section. So, part of this is a bug?

Umm... well, the only bug I know of related to this (assuming using the latest code from common/common.js for resolveReferences) is that if there is IDL that declares a constructor with a name foo, and there is a dfn for foo somewhere else in the document, then the idl processor links to that dfn.... which could be bad if it wasn't a term foo that you wanted.

I will look at core messages to see if there is something else going on.

halindrome commented 8 years ago

I fixed it in the webpayments-core-messages spec. The utils.js script was out of date.

adrianhopebailie commented 8 years ago

Thanks @msporny and @halindrome for your help on this.

+1 to all that has been said above.

Great to have some momentum behind this again!