search

web-payments / web-payments.org

Web Payments website and core specifications
https://web-payments.org/
29 stars 13 forks source link

Create image to summarize payment flow #22

Open msporny opened 10 years ago

msporny commented 10 years ago

It's currently very difficult for readers to understand the basic PaySwarm payment flow for the purchase of an item online. A graphical depiction of the buy flow would help alleviate some of this problem.

The conversation that triggered this issue is here: http://lists.w3.org/Archives/Public/public-webpayments/2014Jan/0039.html

davidlehn commented 10 years ago

I should note that we at @digitalbazaar do have some very old developmental diagrams from the early days of PaySwarm. Some based on old OAuth flows. They would probably be a good start for diagrams that explain the current tech. If someone wanted to work on this issue, please let us know first so we can extract the useful bits. I also had a diagram for the registration flow in the web-api spec that was never finished.

These diagrams were based on the mscgen tool and syntax. It works ok but the output is a bit dry when you compare against seqdiag and other blockdiag project tools.

I was unsure how to integrate diagrams into the specs. My first attempt was just to use a Makefile, have it generate some images, and integrate them with a table+image+caption block in the specs. In that case the generated images need to be under source control too. We might be able to do some nice fallback code and prefer SVG output for modern browsers.

jpotvin commented 10 years ago

If we advance UML models the choice of modeling software will matter, unfortunately, since the XMI standard format for UML files never really quite got full uptake by the competing restrictive solution creators.

I've always used ArgoUML http://argouml.tigris.org/ user, but through some of my clients I see momentum in the past year on the Eclipse-based Papyrus UML modeling solution: http://www.eclipse.org/papyrus/ https://www.eclipsecon.org/europe2013/scade-system-first-industrial-success-eclipse-papyrus-presented-cea

Does this Community agree we should choose a free/libre/open UML modeling solution as our default?

Joseph Potvin

On Tue, Jan 14, 2014 at 2:50 PM, David I. Lehn notifications@github.comwrote:

I should note that we at @digitalbazaar https://github.com/digitalbazaardo have some very old developmental diagrams from the early days of PaySwarm. Some based on old OAuth flows. They would probably be a good start for diagrams that explain the current tech. If someone wanted to work on this issue, please let us know first so we can extract the useful bits. I also had a diagram for the registration flow in the web-api spec that was never finished.

These diagrams were based on the mscgenhttp://www.mcternan.me.uk/mscgen/tool and syntax. It works ok but the output is a bit dry when you compare against seqdiag http://blockdiag.com/en/seqdiag/index.html and other blockdiag http://blockdiag.com/ project tools.

I was unsure how to integrate diagrams into the specs. My first attempt was just to use a Makefile, have it generate some images, and integrate them with a table+image+caption block in the specs. In that case the generated images need to be under source control too. We might be able to do some nice fallback code and prefer SVG output for modern browsers.

— Reply to this email directly or view it on GitHubhttps://github.com/web-payments/web-payments.org/issues/22#issuecomment-32300491 .

Joseph Potvin Operations Manager | Gestionnaire des opérations The Opman Company | La compagnie Opman http://www.projectmanagementhotel.com/projects/opman-portfolio jpotvin@opman.ca Mobile: 819-593-5983 LinkedIn (Google short URL): http://goo.gl/Ssp56

msporny commented 10 years ago

@jpotvin I think the real question is whether we think that we should be doing UML diagrams at all. There are no widely deployed W3C specs that use UML diagrams (probably because Web developers are dubious as to their usefulness in Web specifications). Also keep in mind that most of the specs tend to eschew diagrams for a variety of accessibility reasons, but when they do diagrams, they tend to be pretty simple.

Diagrams in W3C specs are typically a method of last resort.

davidlehn commented 10 years ago

I can't speak for others, but I haven't used or even seen any use of UML for many many years. I'm not sure what communities do use it, but apparently not the ones I'm in or following. In this case I think we are looking to visualize algorithms in order to better explain them. I'm not sure how rigorous we want the diagrams to be compared to the official spec text. That may limit their usefulness for complex tooling. I'd suggest leaning towards simple small tools like the blockdiag ones that use simple text file input that is easy to revision control. For just simple visualizations this may be easier for more people to work with.

jpotvin commented 10 years ago

If the objective is the get buy-in from large complex organizations, which surely is the case here, UML helps to demonstrate "good housekeeping practices" -- even (especially) for agile development teams. This will be particular important to gain trust in the planned workflows for handling payments. It's essential to communicate not only with fellow programmers, but with the semi-technical decision-makers.

Most large private and public sector organizations I engage with require at least some basic UML documentation for significant systems. Having said that, I must admit my "sample size" is small, so I can't claim I seen any trend or proportions. And it seems to be much less popular amongst free/libre/open hackers than the restrictive types.

My recommendation is that Manu ask some of his contacts (eg in SWIFT, FT, etc, maybe some in large orgs on this list) whether having the web payments systems logic documented in UML, and the db in formal ER diagrams would make any difference to how this initiative is viewed within their organizations.

My general assessment is reflected in: http://saturnnetwork.wordpress.com/2010/10/22/five-reasons-developers-dont-use-uml-and-six-reasons-to-use-it/ http://agile.dzone.com/articles/we-do-not-use-uml-we-are-agile

Having said that, it's important to emphasize I'd not be suggesting to go nuts with excessive UML detail which will be impossible to maintain (... unless you're actually running it: https://en.wikipedia.org/wiki/Executable_UML http://www.executableumlbook.com/ )

Joseph

On Tue, Jan 14, 2014 at 7:35 PM, David I. Lehn notifications@github.comwrote:

I can't speak for others, but I haven't used or even seen any use of UML for many many years. I'm not sure what communities do use it, but apparently not the ones I'm in or following. In this case I think we are looking to visualize algorithms in order to better explain them. I'm not sure how rigorous we want the diagrams to be compared to the official spec text. That may limit their usefulness for complex tooling. I'd suggest leaning towards simple small tools like the blockdiag ones that use simple text file input that is easy to revision control. For just simple visualizations this may be easier for more people to work with.

— Reply to this email directly or view it on GitHubhttps://github.com/web-payments/web-payments.org/issues/22#issuecomment-32323755 .

Joseph Potvin Operations Manager | Gestionnaire des opérations The Opman Company | La compagnie Opman http://www.projectmanagementhotel.com/projects/opman-portfolio jpotvin@opman.ca Mobile: 819-593-5983 LinkedIn (Google short URL): http://goo.gl/Ssp56