Move lifecycle section to Use Cases.

[brentzundel]

This PR fixes #1465 by removing sections 3.4 and 5.1 and adding text pointing to the use cases document.

This is related to w3c/vc-use-cases#154 which adds the text from section 3.4 to the use cases document. The text in section 5.1 was largely redundant with text already in the Use Cases document, so it is simply removed.

This PR should not be merged until the related Use Cases PR is merged.

---

Preview | Diff

[iherman]

As part of the move, the diagram diagrams/ecosystemdetail.svg must be moved over to the use case repository, together with the source of the digram, ie, diagrams/ecosystemdetail.drawio. This diagram is indeed included in the second block that has been removed.

Cc @jandrieu @KDean-GS1

[brentzundel]

@iherman good catch, fixed in 3ac48da and 26bb4d8

[brentzundel]

I encourage folks here to also review the related PR w3c/vc-use-cases#154

[David-Chadwick]

I agree with moving the section 3.4 to the use cases, but I think that section 5 should remain in the VCDM, because without it, the lifecycle is no longer described in the VCDM. I don't think people should have to refer to another document in order to delve into the lifecycle in more depth

[brentzundel]

@David-Chadwick if this were v1 of the spec I would completely agree with you.

Since this is v2, I do not believe we need this level of explanatory text alongside the normative requirements.

[David-Chadwick]

Newbies to VCs will not read V1 of the VCDM. V2 will be the first time they see our specification. Thus I maintain that this text should remain in this version.

[David-Chadwick]

Furthermore there is nothing lost by including it. Some oldies may not need it or read it, but since it does not detract from their understanding of V2 of the VCDM then it should be kept.

[TallTed]

I'm afraid I agree with @David-Chadwick.

I note that the issue that drove this PR (#1465) proposed:

merging content from 3.4 into 5.1 so that the spec only has one lifecycle section, also removing the concrete example and instead pointing to the Use Cases note

That is all that is immediately visible on that issue. This PR does rather more than move the concrete example to the Use Cases note.

I do see that #1465 was discussed in one meeting, and a brief vocal exchange among @msporny, @jandrieu, and @brentzundel appears to be what brought about the larger change. (I was present for this meeting, but I'm sorry to say I missed this exchange when it happened.)

I think this PR (and its companion) should be revised to do what was proposed in #1465. I do not think the general description of the VC life cycle can be considered a Use Case.

[brentzundel]

During the call there seemed to be broad support for moving both sections to the use cases doc. In doing so I found the Use cases document already has a far better version of section 5.1, so it doesn't make sense to move it there.
I also don't think it makes sense to keep a poorer version in the VCDM, nor to replace Section 5.1 with the version already in Use Cases. In my mind that leaves us with dropping it.

If others agree that we should keep it that's a simple enough change to this PR, and I'm willing to revert that change if that's what the group wants to do, but I maintain that it isn't necessary and assert that keeping the lifecycle section in the spec makes it less readable and therefore more difficult to implement.

I have been on the receiving end of much criticism of VCDM v1 and v1.1, and one oft-repeated note has been that there is too much cruft, too much philosophy, and too much explaining going on, which takes away from the clarity of the specification. I would like v2 to be better and believe that moving these sections out of the spec is a step toward making it better.

[TallTed]

Could we try to stop referring to sections by number alone, and either include or substitute the section title? The changes being discussed here have side effects of changing the numbers of multiple section, including both those actually touched by these changes and those nearby, making it difficult (at best) to keep mental track of what section is where, especially as these changes impact at least two repositories/documents — via w3c/vc-use-cases#154 and #1476

[brentzundel]

For clarity, the sections referred to in this conversation are Concrete Lifecycle Example and Lifecyle Details

This PR removes both Concrete Lifecycle Example and Lifecyle Details.

w3c/vc-use-cases#154 adds the text from Concrete Lifecycle Example, but only keeps the diagram from Lifecyle Details because VC Use Cases already contains more detailed lifecycle details in User Tasks.

[iherman]

The issue was discussed in a meeting on 2024-04-24

• no resolutions were taken

View the transcript

5.2. Move lifecycle section to Use Cases. (pr vc-data-model#1476)

See github pull request vc-data-model#1476.

Manu Sporny: it seems some level of disagreement on PR #1476.

See github pull request vc-use-cases#154.

Brent Zundel: two lifecycle sections in the spec was moved, the second life cycles was going to be incorporated into the use cases document. Moving the second section to that place seemed unnecessary.
… David Chadwick noted there wasn't any ecosystem section in the spec but the current approach is not to include it and move forward.

Manu Sporny: agrees we don't need the above sections. If something is missing we should have the discussion in the use cases document.

Ivan Herman: wondering whether it's worth having an overview document for all the specs we've done. For an outsider coming in, it appears extremely messy. Some of the things moved to the use cases doc might better be in an overview doc.

Ted Thibodeau Jr.: Agrees an overview doc is called for. Still doesn't make sense to TallTed to consider lifecycle as as use case.

Ted Thibodeau Jr.: +1 nobody coming when v3 or v4 is "current" is going to look to v1 to learn the lifecycle.

David Chadwick: the arguments for removing it are spurious. But people who come to VCDM v2.0 without reading earlier versions because so many newbies are coming to the v2 fresh.
… Value i leaving it in because there value for it in V1.

Manu Sporny: maybe use cases is a temporary location for the lifecycle until we have an overview document. We have one from RWOT that may be usable.

Brent Zundel: chair hat on -Brentz will do whatever the group wants to do. If we move forward would DavidC object?

David Chadwick: no he would not object.

Ivan Herman: See Example for a standards' Overview document for the OWL family.

[selfissued]

I strongly support removing this text from the specification. It does not contain normative statements that are actionable by implementers, and so it rightly belongs in an advisory document, rather than the core specification.

[msporny]

Editorial, multiple reviews, changes requested and made, concerns discussed on a WG call with consensus to merge, no remaining objections, merging.