Create image to summarize payment flow

[msporny]

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]

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]

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//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]

@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]

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]

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//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