Migrate PaymentRequest text from arch to payment request spec.

[msporny]

This pull request migrates the payment request API specific text from the architecture document to a section titled "Payment Request API Architecture" in the payment request specification.

The assertion is that if the WG is going to publish an architecture specification, that it should not only be about the Payment Request API, but also be inclusive of the other specifications we're building in the Web Payments WG (including both browser and HTTP APIs).

Specifically, the architecture document should reflect what @adrianhopebailie wrote in the Web Payments wiki on Architecture as that is a more holistic view of what we're doing that the current architecture document proposed by Microsoft/Google.

So, this PR:

1. Migrates all the Payment Request API specific architecture text and migrates it to a section titled "Payment Request API Architecture" in the payment request specification.
2. Leaves the more general Web Payments API Architecture content in the architecture specification.
3. Preps the architecture specification so that we can move @adrianhopebailie's more holistic architecture text into the spec.

[ianbjacobs]

-1 to this proposal for reasons already cited:

• easier to read by a different audience
• easier to evolve independently.

[msporny]

easier to read by a different audience

What's the audience for the text I'm proposing to migrate?

easier to evolve independently

The text I'm proposing to migrate is tightly bound to the Payment Request API, why does it need to evolve independently?

To be clear, I'm not saying we get rid of the architecture document. I'm saying we move the stuff that is highly specific to the Payment Request API to the Payment Request API document.

[ianbjacobs]

@mpsorny,

What's the audience for the text I'm proposing to migrate?

People who want to understand how the parts fit together without reading WebIDL. This is the level of information I present, for example to different audiences such as the recent AC meeting.

The text I'm proposing to migrate is tightly bound to the Payment Request API, why does it need to evolve independently?

It is rather that it may not have to change even as the API changes. Or, we can augment it to fulfill new communications requirements without having to rev the API document which will be harder to do because if IPR commitments.

I don't mind renaming this "Overview" if the word Architecture is a concern to you.

Ian

[mattsaxon]

I'm in favour of making the overall architecture clear and to differentiate the Web Browser API architecture from the Web Payment Architecture, however could we do this with clear sections in the Architecture document rather than moving the text between documents? This could have placeholders in for the various overview sections, e.g. include a placeholder for the HTTP API saying "to be completed", the document would then be "WebPayments Architecture with API Overviews"

[msporny]

@ianbjacobs wrote:

People who want to understand how the parts fit together without reading WebIDL.

There is no WebIDL in "Section 4: The Payment Request API Architecture" and that section is the only section people will have to read if they want to get an overview of the Payment Request API Architecture. Here is a link to the changed version of the document:

http://manu.sporny.org/tmp/wpwg/browser-payment-api/specs/paymentrequest.html#the-payment-request-api-architecture

It is rather that it may not have to change even as the API changes.

If it doesn't change as the API changes, then the text will remain the same (and not change). No extra work is needed.

Or, we can augment it to fulfill new communications requirements without having to rev the API document which will be harder to do because of IPR commitments.

New communication requirements related to the Payment Request browser API will most likely require new documents. The purpose of the "The Payment Request API Architecture" section is to describe just that (the architecture of the Payment Request browser API)... and that is tightly bound to the browser API and the set of documents around the API that use WebIDL to express concepts. If you take a look at the diagram, you'll see all the specs are rooted on the Payment Request API document. This is a browser-only ecosystem.

I'm also asserting that we're not quite clear on the communication requirements for the "architecture.html" document and that placing the Payment Request API Architecture into that document muddies the waters and misleads readers into thinking that we're building a browser-only ecosystem.

I assert that that we should have a "Web Payments Architecture" document that doesn't insinuate that we're building a browser-only ecosystem.

I'll also note that all the objects in all documents rooted at the Payment Request API Architecture are described in WebIDL, which is problematic when it comes to how to express these objects (such as a payment request) in the HTTP API. I'm assuming that these objects are not going to be expressed in WebIDL, but rather JSON and possibly JSON Schema. So, linking to specifications that only describe payment messages in WebIDL sends the wrong message, which is "this is a browser-only ecosystem", and that's a bad message to send out in an FPWD.

This PR attempts to constructively addresses these concerns above.

[msporny]

I'm in favour of making the overall architecture clear and to differentiate the Web Browser API architecture from the Web Payment Architecture

+1

however could we do this with clear sections in the Architecture document rather than moving the text between documents? This could have placeholders in for the various overview sections, e.g. include a placeholder for the HTTP API saying "to be completed", the document would then be "WebPayments Architecture with API Overviews".

Typically, this is done at W3C via two mechanisms.

1. Architecture
2. Document Overview Primers

I'd be happy to pursue that path. What we have right now is a jumble of the previous two mechanisms.

[adrianba]

When I originally sketched out the architecture document, it was intended to be a documentation architecture that explained the normative dependencies. Central to the idea was that the payment method identifier is defined in its own document that becomes a dependency for many other documents including payment method definitions, registration scenarios, as well as the payment request API itself. This means that the API wouldn't be dependent on any particular payment method and there would be the opportunity for different registration or payment app specifications to evolve at their own pace dependent only on the identifier spec.

There have been changes that try to make the "architecture" document into something that more broadly describes the overall system we're working on. This inevitably leads to some disagreement about the scope of the document as well as particular content. It's not clear to me that we need a document to does this.

At the same time, the introduction section of the PaymentRequest API document is largely copied from Zach's explainer document without much change. I imagine that some of this is out of place in the API document and some of it is probably now inaccurate.

I'm not a fan of migrating the bulk of this content to the API spec because I think it could bring in dependencies that I was trying to avoid. It's might be possible to put some of it in the method identifier spec but I suspect that doing so would also imply dependencies that we want to avoid. After all, it probably makes sense to be able to use the same method identifiers out of the scope of this API and directly related documents.

Since the goal of the architecture document was only ever to publish a working group note, perhaps we can move some of the content into the WG wiki as explanation for some of the early decisions and then remove the architecture document. I think it is a waste of the groups resources to devote so much energy into wrangling out a WG Note when we have more important issues to discuss.

[ianbjacobs]

I would put a hold on this request in any case given larger document reorganization proposals that are naturally occurring; see #138

Ian

[sideshowbarker]

There have been changes that try to make the "architecture" document into something that more broadly describes the overall system we're working on. This inevitably leads to some disagreement about the scope of the document as well as particular content. It's not clear to me that we need a document to does this.

It’s not clear to me either. In years of helping manage work on specs for the platform, I can’t think of any other cases where we felt we needed a doc like the one this one seems to be evolving into. Certainly I can say that we got plenty of complex interrelated technologies specced out with such a doc.

So I feel like we are making the mistake of placing a lot more importance on this doc than it merits. It is not at all clear there is broad interest in it. And certainly, especially relative to the browser API spec, etc., it is not something that is absolutely necessary to get interoperable implementations, nor something that is necessary as far as W3C process is concerned, and getting specs to Recommendation is concerned.

So it seems like there is a significant opportunity cost to the architecture doc in the scope to which it seems to have evolved now. Everybody involved has a discrete amount of time available, and time we continue to spend on the architecture doc is time that could have been spent on, e.g., actually getting blocking issues on the API spec resolved, so that implementations can move forward, and so that we can get the spec to CR in a reasonable amount of time without needing to go back to W3C management and explain why the team contacts and the chairs couldn’t manage to get our work done on time.

Since the goal of the architecture document was only ever to publish a working group note, perhaps we can move some of the content into the WG wiki as explanation for some of the early decisions

I think that’s an excellent concrete suggestion that would also allow the members of the WG who actually care about the contents—as well as members of the community—to more easily collaborate on the contents without obstacles in their way.

and then remove the architecture document.

Yes

I think it is a waste of the groups resources to devote so much energy into wrangling out a WG Note when we have more important issues to discuss.

Yeah, which is what I tried to say in bit more detail above.

[adrianhopebailie]

Given the various new proposals currently in place for new documents and the discussion at #138 I suggest we close this PR

[msporny]

Closing request, it's been overcome by events. I look forward to @adrianhopebailie's architecture document (with normative content) or payment app / payment mediator specs.