Added intended audience, purpose, goals/non-goals #814
Conversation
There was a problem hiding this comment.
While some of this language I think might be helpful, a lot of this PR appears to restate the purposes and goals of w3c standards and audiences for those standards as detailed on the main standards page itself and on related links from that page.
This PR is also missing appropriate <a> tags into definitions as well as has some terminology issues that might cause confusion to some audiences such as "verifiable credential technology" as opposed to something like:
systems that utilize the Verifiable Credential<a href="#core-data-model">data model</a>
Seems like it might be better to move this PR to a draft and get some feedback in...
| <p class="note"> | ||
| If a credential contains a credentialSubject property and it, in turns | ||
| contains an id property, the value of the id property, if present, is to be interpreted | ||
| as an identifier for the corresponding credential subject. | ||
| </p> |
There was a problem hiding this comment.
| <p class="note"> | |
| If a credential contains a credentialSubject property and it, in turns | |
| contains an id property, the value of the id property, if present, is to be interpreted | |
| as an identifier for the corresponding credential subject. | |
| </p> | |
What does this section have to do with "intended audience, purpose, goals" etc. I suggest this paragraph gets pulled, and that where possible we look at one topic per PR
There was a problem hiding this comment.
What does this section have to do with "intended audience, purpose, goals" etc. I suggest this paragraph gets pulled, and that where possible we look at one topic per PR
Killing 2 birds with one stone @mprorock per #800 (comment)
There was a problem hiding this comment.
It's generally not considered friendly collaboration to respond to a request with a "No" and a "conversation resolved" button click. Both parties generally must agree that the conversation has been resolved, before that button should be clicked.
There was a problem hiding this comment.
I think there's a lot that the WG would need to discuss here to ensure it is an accurate reflection of the spec's goals, audience, etc. and that there is consensus on those things. My initial read is that it suggests a much more ambitious spec than it actually is.
| is a broad range of professionals interested in furthering | ||
| the application of verifiable credentials technology for use in software apps, agents, and services. |
There was a problem hiding this comment.
Hmm, I read the meaning of this as "the intended audience for the VC data model spec is people interested in using VC technology" -- which, to me, seems circular and -- therefore, doesn't really add anything for the reader.
I'd think the intended audience would be people that want to express physical or digital documents that include assertions about other people, places, or things in a standard digital format so that they can be more widely consumed -- and so that the documents' authorship can be verified by third parties (verifiers). Or something along those lines. However, this sort of text may already be gleaned from the spec -- so it may just be a restatement of that.
There was a problem hiding this comment.
Hmm, I read the meaning of this as "the intended audience for the VC data model spec is people interested in using VC technology" -- which, to me, seems circular and -- therefore, doesn't really add anything for the reader.
@dlongley What aspect do you think is circular?
I'd think the intended audience would be people that want to express physical or digital documents that include assertions about other people, places, or things in a standard digital format so that they can be more widely consumed -- and so that the documents' authorship can be verified by third parties (verifiers). Or something along those lines. However, this sort of text may already be gleaned from the spec -- so it may just be a restatement of that.
@dlongley I agree that your comments represent a deeper level of detail. I have no problem adding something like:
More specifically, the primary audience is software architects and developers that want to express physical or digital documents that include assertions about other people, places, or things in a standard digital format so that they can be more widely consumed.
...or something like that. I'll wait before making this change.
There was a problem hiding this comment.
Hmm, I read the meaning of this as "the intended audience for the VC data model spec is people interested in using VC technology" -- which, to me, seems circular and -- therefore, doesn't really add anything for the reader.
@dlongley What aspect do you think is circular?
To me, it is saying the intended audience of a spec that defines X are people that are interested in X. This seems largely vacuous to me. It's like reusing the word in its own definition -- and why I described it as circular.
An alternative to this would be to talk about people that are interested in other things that are components of or similar to X -- and therefore a spec that defines X subsumes their interests and standardizes some important element for them to achieve interoperability.
As an example: The intended audience of the 'Fantastic Authorization Token' spec are people who are trying to build interoperable libraries that enable granting third party applications access to restricted resources.
As a counter example: The intended audience of the 'Fantastic Authorization Token' spec are people who are interested in using Fantastic Authorization Token technology.
There was a problem hiding this comment.
@dlongley first, thank you for the dialog and moving this forward
Second, counter example:
This is a football book (or book about football) that is expected to be of interest to people interested in professional football ...a bit wordy
There was a problem hiding this comment.
"the intended audience for the VC data model spec is people interested in using VC technology"
@dlongley IMO, your paraphrasing isn't quite right. Try this:
"the intended audience for [this document aka Recommendation] is people interested in using VC technology"
I think this makes sense (and the original wording more correct) ...but I will endeavor to refine it some more in the next go-around.
There was a problem hiding this comment.
If I were copy editing something that had this statement:
"This is a football book (or book about football) that is expected to be of interest to people interested in professional football ..."
I'd recommend cutting it because it doesn't add value. Of course a football book is expected to be of interest to people interested in football. If the statement is to be of value, it should explain a bit more, for example, this is a football book that is expected to be of interest to people who would like to know more about defensive strategies to employ against well known offensive strategies (or whatever).
I'd say that the goal of mentioning an intended audience for a document is to narrow (or highlight) something that wouldn't otherwise be known from the title of the document or the rest of its basic introduction. If we're not adding more information with the statement, then I'd consider it is a net negative on the document; it makes it more verbose or complex which is an unnecessary burden on readers and/or maintainers. I think we should want to make a specification as short as possible (but not shorter) :).
| The primary audience includes software architects, application developers, and user experience (UX) | ||
| specialists; |
There was a problem hiding this comment.
I'm not sure that this is actually the primary audience. At least, I'd think we'd be highlighting credential authors and consumers more as opposed to "software architects" and "UX specialists". If I were someone that needed to figure out how to express credential information for some use case or to know how my application will consume it/which parts my application may need to consume (or how to build verification software), this is the spec for me. What do others think?
There was a problem hiding this comment.
highlighting credential authors and consumers more as opposed to "software architects" and "UX specialists".
Who are these people in real life? ...that is, credential authors and consumers. Who are these people on your VC-based app project team? I think we need words (audience roles) that identify with real people and their roles. Further, credential authors and consumers sound like users of a verifiable credential-based system ...not designers and builders of VC-based systems. The later IMO is who we're targeting. Correct?
If I were someone that needed to figure out how to express credential information for some use case or to know how my application will consume it/which parts my application may need to consume (or how to build verification software), this is the spec for me. What do others think?
The answer is actually "no" IMO. The proposed Guide (in addition to the Documentation consisting of the VC data model recommendation, the VC use cases note, and the other 3rd document whose formal name escapes me) is what people (architects and developers) need to read.
Aside: Perhaps business analysts could or should be added to the intended audience statement?
Caution: Think of the intended audience statement as a commitment or contract with the intended readers of the Recommendation. So, for example, if we chose to add any role (e.g. business analyst), we need to make sure there is sufficient content of sufficient relevance and depth to satisfy readers assigned to the particular role.
For v1.1 specifically, I believe we want to err on the side of a limited set of roles at this point in the review/approval process.
There was a problem hiding this comment.
Who are these people in real life? ...that is, credential authors and consumers. Who are these people on your VC-based app project team?
Well, I would not say that they are software architects or UX specialists. Neither of these roles seem to fit to me (at least not as top of mind). A data modeler/data engineer would fit better as a "credential author".
I think we need words (audience roles) that identify with real people and their roles. Further, credential authors and consumers sound like users of a verifiable credential-based system ...not designers and builders of VC-based systems. The later IMO is who we're targeting. Correct?
Yeah, "consumer" may not be a good name here for the reason you mention. A software engineer, application developer, or security specialist may be interested / participate in writing software to consume or verify VCs in the way that I meant.
My point was that I'd think the primary audience of the spec is those authoring VCs (dealing with data modeling and vocabularies, etc.) and the secondary audience would be those creating software to consume and verify them.
There was a problem hiding this comment.
My point was that I'd think the primary audience of the spec is those authoring VCs (dealing with data modeling and vocabularies, etc.) and the secondary audience would be those creating software to consume and verify them.
"authoring VCs" or "designing and building software systems capable of creating, transforming, and verifying VCs?
"authoring VCs" sounds too much like someone who is handcrafting the VC JSON (IMO)
There was a problem hiding this comment.
"authoring VCs" sounds too much like someone who is handcrafting the VC JSON (IMO)
That's right -- I think they are the primary audience.
The spec's main focus is on data modeling (it's right there in the title) -- and telling this audience how they need to go about modeling their data so it fits the standard, i.e., how to model the issuer, dates, schemas, status, that the fact that a VC is about one or more credential subjects and where to put that information, about how claims are subject+property+value (and how a value can itself be another subject with an identifier and more claims), showing examples on how to do extensions and include contexts, etc. All of this is about how to "craft" a VC so it will be processable by tools written against the standard.
So, yes, I think the primary audience is those people doing the crafting and the secondary audience is those people writing software to process what's been crafted.
| The purpose of this Recommendation is to assist the intended audience by providing a deeper understanding | ||
| of what a verifiable credential is as well as how to use verifiable credentials technology | ||
| when designing and creating new software apps, agents, and services. |
There was a problem hiding this comment.
I think the purpose of the spec is to tell readers how to express digital credentials in a standard format (and things along those lines), not tell people how to use VC technology. I'm also not sure that saying that the spec should give people a "deeper understanding of what a verifiable credential is" makes sense -- the spec defines what a VC is. We could say that the purpose of the VC spec is to define what a VC is ... but that's also perhaps unnecessary or self-explanatory.
There was a problem hiding this comment.
We could say that the purpose of the VC spec is to define what a VC is
Good feedback. The PR was intended to be a first draft - to be improved along these lines.
Aside: My original wording assumed the reader would be arriving to read the Documentation with some level of awareness of what a VC is. I have no problem simplifying this sentence. I'll wait and try to incorporate all of the changes at the same time.
| encapsulate a broad range of personal, business, governmental, and | ||
| other types of data including (but not limited to) | ||
| passports, drivers licenses, health passes, travel documents, business documents | ||
| (e.g. purchases orders, invoices, etc.), IoT messages, etc. |
There was a problem hiding this comment.
I think linking to the use cases document may be better (and I think/hope we already do so).
There was a problem hiding this comment.
I think linking to the use cases document may be better (and I think/hope we already do so).
I generally agree. My solution to this was to delegate the cross-linking of the documents in the Documentation to the Guide (w3c-ccg/community#206) ...rather than try to cross-link all of the individual documents in the Documentation.
Thinking with the mindset of the intended audience (intended reader), virtually no one reads the top-level documents. They google for any sort of documentation related to a topic (e.g. verifiable credentials) and start reading from there. This is an example of why the intended audience statement is so important - it causes you to think more specifically about how your targeted reader (aka persona) thinks and acts when looking for information. |
FYI: as a writer, these tags aren't something I would add until near the end of the Collaborate phase...
|
msporny
added
editorial
|
The issue was discussed in a meeting on 2021-09-15
View the transcript3.5. Added intended audience, purpose, goals/non-goals (pr vc-data-model#814)See github pull request #814.
Brent Zundel: 814 is intended audience purpose and goals and non-goals. Dave Longley: Sure. My feedback is largely around do we agree on the purpose and intended audience. Brent Zundel: +1, please review.
|
|
The issue was discussed in a meeting on 2021-09-29
View the transcript1.1. Added intended audience, purpose, goals/non-goals (pr vc-data-model#814)See github pull request #814. Wayne Chang: Michael, can you give us a summary? Michael Herman: I started a process there, good feedback, responded to some of that feedback. I've incorporated a lot of feedback into local copy, busy w/ other things, can respond to comments that are there. Manu Sporny: I was waiting for those changes to come in to do a re-review because there was quite a bit of discussion between Michael and Dave. Michael Herman: I accept that and it's all interconnected. I think this is also text that would be in the guide I'm working on. I apologize for the time it's been taking. Wayne Chang: That it might have another home might also help reduce the size of the text here. |
|
@mwherman2000 can you give us a concrete timeline for when you anticipate being able to make progress on this PR? |
|
The issue was discussed in a meeting on 2021-11-10
View the transcript3.2. Added intended audience, purpose, goals/non-goals (pr vc-data-model#814)See github pull request vc-data-model#814. Manu Sporny: Michael said he would create a separate document to address his concerns. David Chadwick: I agreed to be the 2nd author w/ Michael on his proposed document, but I have not seen a new draft, haven't heard from him in a while.. Brent Zundel: We don't want this to just sit either, been discussed several times in meetings w/ no progress.. Dave Longley: suggests we give this a time limit and then close it. Ted Thibodeau Jr.: we don't want to instigate unhelpful reactions. Brent Zundel: I will ping Michael and ask him when he might be able to move this forward. |
|
@mwherman2000 if we don't hear from you in the next 7 days with a concrete timeline for making progress, we will be closing this PR. |
brentzundel
added
pending close
msporny
added
PossibleErratum
|
The issue was discussed in a meeting on 2021-11-17
View the transcript3.1. Added intended audience, purpose, goals/non-goals (pr vc-data-model#814)See github pull request vc-data-model#814. Brent Zundel: I believe we discussed this last time. Manu Sporny: How long do we wait for a non-response to close a PR?. Brent Zundel: is there any issues with this course of action?. David Chadwick: can we add a pending close label on it?. Brent Zundel: yeah we can do that and I'll ping Michael Herman now. Manu Sporny: we should also remove the other labels if you're ok with that. Brent Zundel: I'm good with leaving V1.1 editorial but we can remove Manu Sporny: Does Editorial label do anything for Errata document?. Kyle Den Hartog: No only |
msporny
removed
PossibleErratum
Addresses:
Preview | Diff