RE: Diagrams for VC HTTP API work [was Re: [AGENDA] VC HTTP API Work Item - August 17th 2021]

In my experience as a writer, the amount of necessary detail in a diagram is primarily (almost solely) driven by: a) the purpose of the diagram, and b) the intended audience; in fact, I'll say the intended audience is the dominant criteria relative to the particular message you're trying to convey.



IMO every deliverable should have a specific statement about the intended audience.  It’s easy to recognize documents that don’t have an intended audience statement: the message/story tends to wander all over the place. An example of an intended audience statement is: https://github.com/mwherman2000/VC-ARM/blob/main/AUDIENCE


Think of an intended audience statement as a commitment you make, as a writer, to your intended readers.



Lastly, IMO, it's almost impossible to add detail later (without starting from scratch).  IMO, the more details you can add to a model, the better.  From this underlying model, you can create an entire range of diagrams for almost any purpose, any audience, any level of detail, etc.



Model your drawings; don't draw your drawings (if that makes sense); check out https://mwherman2000.github.io/VC-ARM/



Best regards,
Michael Herman
Far Left Self-Sovereignist

Self-Sovereign Blockchain Architect
Trusted Digital Web
Hyperonomy Digital Identity Lab
Parallelspace Corporation

[cid:image002.jpg@01D7966E.26F5C950]






-----Original Message-----
From: Manu Sporny <msporny@digitalbazaar.com>
Sent: August 21, 2021 6:34 AM
To: public-credentials@w3.org
Subject: Re: Diagrams for VC HTTP API work [was Re: [AGENDA] VC HTTP API Work Item - August 17th 2021]



On 8/21/21 1:18 AM, Moses Ma wrote:

> If you, or any of the others, think this might have some potential for

> better explaining how VCs would work than the more "programmer

> centric" diagrams you produced, I'd love to participate in a small

> work project with a small number of us to figure out a meaningful

> standardized approach to visualizing VC processes.



Yes x 1000!



One of the biggest problems with the way we present material (for any technical standard, really) is that it exposes the reader to far too much detail.



Case in point, the Web Authentication API:



https://www.w3.org/TR/webauthn-2/#sctn-api




We spent an enormous amount of effort to get these diagrams right in the VC Data Model:



https://www.w3.org/TR/vc-data-model/#roles


https://www.w3.org/TR/vc-data-model/#core-data-model




With an enormous shout out to Dave Crocker, who was fundamental in getting us to "leave out all the important details".



I really like your first cut Moses... now, to make it even SIMPLER!



-- manu



--

Manu Sporny - https://www.linkedin.com/in/manusporny/


Founder/CEO - Digital Bazaar, Inc.

News: Digital Bazaar Announces New Case Studies (2021) https://www.digitalbazaar.com/