Re: [browser-payment-api] Merge Payment Request Architecture with Capabilities Document (#42)

@ianbjacobs wrote:
> This has been done for previous sets of specifications (e.g., OWL, PROV, RIF).

Yes, but in each of those cases the published document was done as a "Document Overview"... not an "Architecture" document. In addition, the Payment Request API Architecture document says things like this:

> ... the anticipated user experience will help explain the architecture:
> 1. At the end of shopping on a merchant site, the user pushes the “buy” button.
> 2. The merchant site calls the payment API with purchase amount, currency, accepted payment methods (e.g., Visa, Paypal, Bitcoin), and any custom data for those payment methods.

That is solely about the browser API and does not take any sort of HTTP API into account. Most of the document is like that, so it's about the Payment Request API and is not a "Document Overview".

We don't gain anything by publishing a document that has questionable benefit at best and could result in a fair amount of miscommunication in the average case. People could walk away from an FPWD reading of the document and think that all we care about is the browser (which we don't). The Payment Request API Architecture document currently reads as if it is *the* architecture document for Web Payments. It's clearly not.

Many specifications at W3C (rightly) integrate this sort of stuff into the front-matter of the specification. For example, HTML5 does this:

https://www.w3.org/TR/html5/introduction.html#a-quick-introduction-to-html

DOM4 does this:

https://www.w3.org/TR/domcore/#goals

SVG does this:

https://www.w3.org/TR/SVG/concepts.html

and so on and so forth.

I do not support FPWD publication of this document at this time but would support the following counter-proposal.

PROPOSAL: Integrate the majority of the Payment Request API Architecture document into the front-matter of the Payment Request API spec. The editors will do the work to integrate this after the Payment Request API FPWD in order to give the group enough time to review the changes.


---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/issues/42#issuecomment-197611787