Re: VCTF Use Cases [RE: Verifiable Claims Telecon Minutes for 2016-04-19]

Steven,

Lots of great suggestions.  I have only one general "as editor" response
I'd like to make by way of explanation, and then we as a group can decide
how we want to proceed.  The editors were careful to take the use cases
that were sent in largely as-is.  We adjusted "credentials" to "verifiable
claims" and did many other similar terminology changes that the group
wanted, but in general we erred on the side of not risking a change that
would make the use case different from what was originally provided.

Given that, I personally agree with you that some sanitizing would be
helpful.  A variety of made-up individual names is, I think, helpful, but
the humorous or snarky names for companies probably are not.

One approach might be to encourage suggestions for improvement, either in
email or, ideally, as GitHub Pull Requests, along with encouraging those
who provided use cases to verify occasionally that the spirit of their
request hasn't been lost as we apply some of those PRs.

-- dan

On Wed, Apr 20, 2016 at 1:16 AM, Steven Rowat <steven_rowat@sunshine.net>
wrote:

> On 4/19/16 10:12 AM, msporny@digitalbazaar.com wrote:
>
>> Use cases doc is suffering from
>>    lack of reviews.
>>
>
> I have some comments on this VCTF use-cases draft, which I think is
> current:
> http://w3c.github.io/webpayments-ig/VCTF/use-cases/index.html
>
> I've left them in the order I made them while reading.
>
> [No issues until...]
>
> "Status of This Document"
>
> Minor suggestion -- why not link the words "Charter for a Verifiable
> Claims Working Group" to the Charter. Most other things are linked, and
> this one is specifically stated there as needing to be read in conjunction
> with the Use Cases document. So I expected a link.
>
> "Terminology"
> "Claim"
> On reading the first term, 'claim', and then following the two terms
> introduced in it, 'entity', and 'identity', to their definitions later in
> the list, it took me a couple of readings of all three to understand that
> there was no recursive loop set up between Entity and Identity. At first it
> seemed like there might be, which was disorienting my ability to continue
> down the list.
>
> What I mean is: what is presupposed here by the Editors -- as I eventually
> understood it -- is that an 'entity' actually exists in the world somewhere
> (otherwise it couldn't make a statement, and nothing else would matter).
> Whereas the 'identity' being defined only exists insofar as the verifiable
> claim process is completed, or at least followed.
>
> So: 'identity' is being *defined by the steps of the system*, whereas
> 'entity' is *pre-existing outside the system*.
>
> I think this might be spelled out better, especially in that first
> encountering. The fact that the listing of terms is alphabetical and so
> 'claim' is encountered first is essentially random, and it might be good to
> be careful that the first encountering of 'entity' and 'identity', which
> happens here, doesn't allow the reader to think that, say, both entity and
> identity exist outside the system, or both are only defined within the
> system, or that identity exists outside and entity is defined inside it.
>
> In other words, if the naive reader has some biases about those two words
> 'entity' and 'identify' already and, without guidance at this point, makes
> assumptions about how they're used, then in three out of four of those
> assumptions they're going to be wrong and have to re-orient themselves
> again later. Maybe best to correct them right at the start. :-)
>
> "Credential"
> If 'identity' is used again here without a solution to the problem of
> definition I just described having been given, this could allow the reader
> to continue to entrench an incorrect assumption about 'identity'.
>
> "Credential consumer"
> Ditto about 'entity'. More entrenching of possible wrong understanding.
>
> "Entity"
> Now there is a clear statement; but I suggest that this statement needs to
> go at the start. So I believe it would be best not to use alphabetical
> listing. I think this statement is a key one and should be encountered
> early or first.
>
> In fact, looking at the next two, 'Holder' and 'Identity', I now think
> overall that "Terminology" should be re-ordered to unfold in a way that
> makes it easiest for the reader to both map the terms with their
> specialized meanings and to follow the flow of the basic mechanism of the
> VC.
>
> I think there are a small enough number of terms that alphabetical-ness
> isn't really required. It's more important to follow the flow and
> definitions correctly the first time through than to be able to find them
> quickly later. It's not hard to scan ten bold words and find the one you
> want, whatever order they're in.
>
> "4.1.1 Uniquitous Claim Issuance"
> "Uniquitous" -- I found no match in three dictionaries I tried. Google
> search shows 26 million hits for 'ubiquitous' and 21 thousand for
> 'uniquitous'. I's an interesting word, but that's three orders of
> magnitude. I think it might be best to avoid it, in the interests of less
> obfuscation (3 million hits. ;-) ).
>
> First scenario - typo: needs period after 'money laundering'.
>
> All scenarios: why are some uses of 'credential' and other glossary terms
> linked, and not others. I suggest either link all, link none, or link only
> those in the first scenario under each section.
>
> All scenarios: In first two scenarios (Jane, Midbank, Joleen, Mega U.) the
> goals of the person are not immediately apparent; I had to puzzle them out
> a bit, especially in the second, the 'extended transcript'. Whereas the
> third and fourth ones are simpler and clearer. I suggest reversing the
> order, and where possible, in all sections, put the simplest and clearest
> instances first.
>
> 4.1.2
> "Editor's note" : doesn't make sense. We're in 4.1.2, so I don't know what
> referent is.
>
> "4.2.1 Issuer Revokes Claim"
> Scenarios
> Barney and Jane have been encountered before. Other names are new, like
> John and Big Bank. I think this is causing my brain to lose the meta-plot
> here, and get confused about who is what and what's happening where. So I
> think either:
>
>   a) a small group of consistently-named people and entities should be
> followed through all the steps, start to finish of all the use-cases; or
>
>   b) use new names in all cases for each instance in every use case.
>
> Otherwise I think some human brains will naturally strain to see the
> pattern, and expect the stories to continue (since some of them do), and be
> confused about whether they do or don't.
>
> Plus, either way, I think the naming of entities could be simplified and
> some deleted; it seems preferable to me to say John or Jane uses 'a bank'
> in a given scenario. [For example, I found I was relieved when reading the
> section 4.4.3 Pseudo-Anonymity scenarios, which had only one named entity
> in each of the first two scenarios -- June and a 'beer and wine store',
> John and 'a clinic'. I found these easier to follow.]
>
> "4.3.1 Portability of Claims"
> Again...with all due respect, in my opinion the possible tangents
> introduced in people's minds by BigBank, WallStreetCo, Wossamotta U., and
> Moosylvania -- such as, perhaps, "Too Big To Fail" and/or college humor --
> are unnecessary and distracting in a document as important and potentially
> difficult to understand as this one. It sounds boring maybe, but I think as
> many terms as is possible should be made neutral, so that the ones being
> defined will stand out without distraction.
>
> "4.4.2 Consumer Verifies Claim"
> "Requirement."
> What is the "credential identifier". Is this related to 'identity'? I'm
> lost in this paragraph from that term onwards. And the term doesn't exist
> anywhere else in the document (search doesn't find it).
>
>
> That's it, no issues after that.  :-)
>
>
> Steven Rowat
>
>