Verifiable Credentials Guide (VC-GUIDE)

[mwherman2000]

New Work Item Proposal

See W3C-CCG New Work Item Process

Include Link to Abstract or Draft

• [VC-GUIDE] https://github.com/mwherman2000/vc-guide

List Owners

• Michael Herman (Trusted Digital Web) - @mwherman2000
• David Chadwick (University of Kent) - @David-Chadwick

@David-Chadwick is also serving as the primary (initial) person assigned to the role of W3C experienced work item owner/editor/contributor assisting @mwherman2000.

Work Item Questions

1. Explain what you are trying to do using no jargon or acronyms.

Create a W3C Community Note entitled Verifiable Credentials Guide that satisfies the following Goals, Non-Goals, and Intended Audience statements.

Goals

• Provide a first entry point or landing area for members of the intended audience to:
  1. Help readers locate each of the documents that are part of the collection of [VCWG] deliverables that, in turn, describe what Verifiable Credentials are and how to use them ("Documentation"); as well as how to test conformance of a Verifiable Credential implementation against the Documentation.
  2. Help readers understand the purpose of each deliverable in the Documentation as well as understand the relationships between each pair of the deliverables (as appropriate).
  3. For specific key topics, understand where in the Documentation to look for help; for example, key topics might include Data Model, Conformance, Use Cases, Specific Data Platform Considerations, External Resources, etc.
  4. Project the Documentation as a comprehensive body of knowledge about Verified Credentials (or at least a great starting point).

Non-Goals

• The guide is not a Primer in the classic W3C sense. A list of Primer examples is available in the CCG mailing list.

Intended Audience

• The intended audience for the [VC-GUIDE] is a broad range of professionals interested in furthering the application of Verifiable Credentials technology for use in software apps, agents, and services. The primary audience includes software architects, application developers, and user experience (UX) specialists; as well as other people involved in a broad range of standards efforts related to decentralized identity, verifiable credentials, and secure storage.

2. How is it done today, and what are the limits of the current practice?

   • Nothing similar exists today (possibly with the exception being the Verified Credential Data Model charter document (which was not written with the above goals in mind)). There is no existing guidance or cross-reference that describes, guides people in their use of, nor interconnects the existing deliverables in the Documentation.

3. What is new in your approach and why do you think it will be successful?

   • Initial positive feedback from community members as well as the [VCWG] chairs and [VC-DATA-MODEL] editors. Reference: https://github.com/w3c/vc-data-model/issues/797#issuecomment-906171262
   • Concerns and objections, particularly from members of the (external/outside) Developer audience, that the current [VC-DATA-MODEL] is not implementable based on the actual text of the recommendation. Reference: https://github.com/w3c/vc-data-model/issues/797
   • The [VC-GUIDE], 3-5 pages of body text, can be completed fairly quickly, without too much contention, and still provide significant value – for the stated intended audience (possibly in the 1.1/1.2 timeframe without impacting the 1.1/1.2 schedule …or with very minimal impact).

4. How are you involving participants from multiple skill sets and global locations in this work item? (Skill sets: technical, design, product, marketing, anthropological, and UX. Global locations: the Americas, APAC, Europe, Middle East.)

   • Use of 2 geographically dispersed editors living in vastly different time zones (Western Canada and the United Kingdom)
   • Use of the CCG mailing list
   • Use of GitHub issues and discussions

NOTE: The expected limited length and scope of the [VC-GUIDE] reduces these requirements somewhat. The expected amount of elapsed (calendar) time from the start of this work item to its successful completion is expected to be small (a couple of weeks?). See Process and Plan below.

5. What actions are you taking to make this work item accessible to a non-technical audience?
   • The text of the [VC-GUIDE] is expected to be almost entirely non-normative and less technical based on the nature of the guidance to be included in the guide.
   • The guide, in an odd sort of way, will likely enhance the verifiable credential experience for a non-technical audience by providing clear and understandable descriptions and guidance for the Documentation. This guide may end up meeting most (or all) of their needs in their search for a basic understanding of the Documentation.
   • Minimal use of acronyms ("VC" is not to be used anywhere, for example).

Process and Plan

The writing process to be used for the guide is based on a severely contracted version of the following...

[wyc]

Hi @mwherman2000, this is excellent. Thank you so much for putting this together. I have reviewed your answers to the questions, found them more than satisfactory, and approve this work item. I will especially note that:

• This solves a clear pain point for new members entering our ecosystem who come from a technical background. Even if someone is technically inclined, they usually aren't familiar with the specific terminology and jargon that this community uses--a huge barrier to adoption that this work item could help address head on.
• @mwherman2000, you seem to have experienced this pain point yourself fairly recently, and this could be an opportune moment to document the right passageway for others.
• There is a clear roadmap and project management structure, which greatly increases the chance of success.

Thanks for identifying a pain point for the community and volunteering your time & expertise to do something about it! I am in strong support of this moving forward, and with two co-owners from different orgs I see no obstacles to this.

cc @vsnt @mprorock for your opinions.

[mwherman2000]

Announcement of this Work Item Proposal was emailed to the CCG email distribution list today (Monday, August 30, 2021). [Date corrected]

Announcement of a new W3C Community Note Work Item Proposal entitled Verifiable Credentials Guide.

Links

1. Work Item documentation: Verifiable Credentials Guide (VC-GUIDE) #206
2. Initial repository: https://github.com/mwherman2000/vc-guide
3. Initial draft and outline of the W3C Community Note: https://mwherman2000.github.io/vc-guide/
4. Statements of support: https://github.com/w3c-ccg/community/issues/206#issuecomment-907836338

Feedback

• Work Item Proposal Feedback: Please provide your feedback by replying to this email, by contacting one of the editors, or by posting your feedback here: https://github.com/w3c-ccg/community/issues/206
• VC-GUIDE W3C Community Note: Please provide your feedback by replying to this email, by contacting one of the editors, or by posting your feedback here: https://github.com/mwherman2000/vc-guide/issues

[vsnt]

@iherman I think you mean today - Aug 30, not the 20th.

I recommend discussing this work item at an upcoming CCG main call.

I personally would like to see specific, measurable goals for including a diverse set of perspectives/material into the final result. For example, if you can't recruit a diverse group of participants to work on the work item, can you interview a diverse number of viewpoints and incorporate their perspectives into the final document in a positive and reflective way?

[mwherman2000]

@iherman I think you mean today - Aug 30, not the 20th.

@vsnt, it's @mwherman2000 ...and no 🙂, we're not related 🙂 as far as I know 🙂

I recommend discussing this work item at an upcoming CCG main call.

I'm available most any day next week or the week after. As lead editor, I'm looking forward to moderating this conversation/discussion.

My preference is for the discussion to be "topic based"; that is, each segment of the conversation is related to a specific posted issue, submitted PR, or (new process idea) "q+ my favorite topic". The moderator will declare a particular "topic open/active" and we q+ until we have more or less exhausted that topic. Then the moderator can declare the next topic to be open, etc. Every topic gets a proper shot at being discussed (rather than becoming a "shot in the dark" recorded in the transcript (and forgotten)).

I personally would like to see specific, measurable goals for including a diverse set of perspectives/material into the final result.

I agree that, for this Guide (as well as most CCG work items), the discussion and content will be primarily guided by those who "show up".

However, one thing I can commit to (now) is using my vast social networks (e.g. 14,000 LinkedIn connections, plus Twitter, blog, and Facebook ...beyond the CCG mailing list) to broadly publicize work on the Guide.

Also note, I will be working to honour the commitment to produce the Guide in a relatively short period of time ...which tends works against building broad social involvement.

For example, if you can't recruit a diverse group of participants to work on the work item, can you interview a diverse number of viewpoints and incorporate their perspectives into the final document in a positive and reflective way?

Thank you for the feedback. I will endeavour to do this. I believe in it but it will ultimately be determined by those who show up.

p.s. Note: the Guide has a somewhat tightly defined intended audience statement which will expectedly result in some self-selection on the part of those who choose to get involved with the Guide.

[mwherman2000]

@vsnt Invitations to participate in the creation of the Verifiable Credentials Guide were posted earlier today to:

• LinkedIn - 14,500 connections (317 views, 1 reshare to date: https://www.linkedin.com/feed/update/urn:li:activity:6840415741024595968/ca/share-analytics/)
• Facebook - 600 direct friends (1 reshare to date)
• Twitter - 1000 followers (1360 views, 38 engagements to date)
• Hyperonomy Blog - about 1000 views per month

Here's the specific announcement/calls for participation links:

• https://www.linkedin.com/posts/mwherman_digitalidentity-decentralizedidentity-verifiablecredentials-activity-6840415741024595968-6vsE
• https://www.facebook.com/mwherman/posts/10159115437045932
• https://twitter.com/mwherman2000/status/1434652168179486722
• https://hyperonomy.com/2021/09/06/verifiable-credentials-guide-for-developer-call-for-participation/

[launganik]

@mwherman2000 is the expectation for everyone to come up with their own versions of this guide from scratch? Can I collab with existing guide builders?

[mwherman2000]

@mwherman2000 is the expectation for everyone to come up with their own versions of this guide from scratch? Can I collab with existing guide builders?

@launganik Thank you for asking the how do we get going question.

I'll more than likely carry the vision for the Guide forward by writing the first draft with reviews, feedback, and changes at each step. ... asking for expert help for key sections like the Data Platform Bindings subsections.

Checkout https://mwherman2000.github.io/vc-guide/ for an initial outline. You can begin now to file issues documenting your input, feedback, other thoughts here: https://github.com/mwherman2000/vc-guide/issues . I would love to start getting feedback asap.

Once we get some consensus on the scope and outline, we can refine the process/plan/schedule. A detailed process appears at the bottom of https://github.com/w3c-ccg/community/issues/206#issue-981865618

Here's a simpler version that I've also used... Reference: https://hyperonomy.com/2016/05/09/how-do-we-think-about-how-we-work/

@launganik how does that sound? Thank you for engaging early.

p.s. We're still combining this week: https://youtu.be/uDsUbhLB5lI . I'll start working on the Guide more full-time next week.

[launganik]

@mwherman2000 I can help out with documenting VC use cases. My team has done some work around this. Do you need help there?

[mwherman2000]

@mwherman2000 I can help out with documenting VC use cases. My team has done some work around this. Do you need help there?

@launganik VC use cases is a separate document - one of the 3 documents in the Documentation that the Guide will provide an overview of and some insight into. Checkout https://www.w3.org/TR/vc-use-cases/

Suggestion: Review the current VC use cases document (as well as the current issues list) and provide any unique feedback you have here: https://github.com/w3c/vc-use-cases/issues/

[mprorock]

I would like to see a co-owner that has authored one of the widely used open source VC libraries given that this is intended to be a developer guide before approval of this work item. This is to ensure that historical lessons learned are conveyed well, and also to help ensure that the guide conforms well to the VC Data Model spec, including items that are best practices but not necessarily normative.

[mwherman2000]

@mprorock Maybe the working title "Guide for Developers" isn't the best choice.

This isn't a Developer's Guide but rather an overview guide targeted at developers. ...a "Guide for Developers" would be closer to what a Primer is ...one of the specific nongoals for the Guide.

[mprorock]

This isn't a Developer's Guide but rather an overview guide targeted at developers. ...a "Guide for Developers" would be closer to what a Primer is ...one of the specific nongoals for the Guide.

Yeah, titling may need to be adjusted. Going back and re-reading the goals in detail this seems more like an index of resources related to the VC Ecosystem. Is that a correct read?

[mwherman2000]

RE: this seems more like an index of resources related to the VC Ecosystem. Is that a correct read?

No, it's more narrative than just being an "index of resources" ...more like "help text". I'll starting writing next week do give everyone more of a flavor of what I have in mind (which I feel is already expressed in the Work Item Proposal).

[mprorock]

I'll starting writing next week do give everyone more of a flavor of what I have in mind

That would be helpful in assessment for sure. Especially if there will be narrative aspects, as well as being focused towards developers I think incorporating a leading developer in the space as mentioned would be highly important.

[mwherman2000]

RE: I think incorporating a leading developer in the space as mentioned would be highly important.

@mprorock Recommendations? I can reach out.

As I've mentioned above, SME have already been identified for the different data platform binding sections. I'm sure and expect they will also comment on the overall content.

[mprorock]

I would look at the following projects that are widely in use: Spruce / DID Kit - Wayne, etc. Transmute / Verifiable data - Orie Securekey / Hyperledger Aries - Troy Digital Bazaar - Manu

I probably missed a few

[mwherman2000]

This isn't a Developer's Guide but rather an overview guide targeted at developers. ...a "Guide for Developers" would be closer to what a Primer is ...one of the specific nongoals for the Guide.

Yeah, titling may need to be adjusted. Going back and re-reading the goals in detail this seems more like an index of resources related to the VC Ecosystem. Is that a correct read?

Guide retitled to Verifiable Credentials Guide (VC-GUIDE) ...with the identical intended audience statement.

[wyc]

@mprorock @mwherman2000 @David-Chadwick I volunteer for co-owner of this work item, does that work for everyone?

[mprorock]

I volunteer for co-owner of this work item, does that work for everyone?

Possibly. A question I have however is that this feels like it could be duplicate effort of the VC-IMP-GUIDE or at least a lot of overlap. @wyc Would effort possibly be better spent adding content there? Or is another direction that doesn't overlap desired?

[vsnt]

I have added this work item to the 9/21 CCG call agenda to review+discuss with the community. Would the owners please attend this meeting. Thank you. https://lists.w3.org/Archives/Public/public-credentials/2021Sep/0074.html

[vsnt]

Work item owners did not attend the 9/21 call, so this work item was not discussed.

[vsnt]

@mwherman2000 are you still interested in pursuing this work item? Please advise, so we can get you on the calendar.

[mprorock]

Closing unless there is further interest to re-open