Retro-documentation efforts towards UCR documentation

[bumblefudge]

Here are some notes on the last few weeks' informal discussions about expanding the VC-HTTP-API to accomodate the kind of enterprise use-cases both inside and outside the SVIP program that many core contributors to the traceability vocab have been doing. The goal, however, is to frame requirements and use cases as generically as possible, NOT to retro-specify what's already built!

Live google doc and PDF for archival purposes:
https://docs.google.com/document/d/1-u0_Ub6feiX6DH3jXFJFjt6n3CwKGpkmC3VISqDkWL4/edit#
VC-HTTP-API Use Cases - archival.pdf

[bumblefudge]

Note: as per last Thursday's call, the goal is to get input towards an initial PR into the API repo for a UCR document.

[msporny]

The goal, however, is to frame requirements and use cases as generically as possible, NOT to retro-specify what's already built!

While I agree with this to a degree. The stuff that was built was built for a reason, and it really shouldn't be hard to document the use cases that led to what was built.

We may want to start out and ensure that vc-http-api-use-cases is a repo... use cases are typically separate documents from the main spec.

[TallTed]

A separate document doesn't necessarily require its own repo, though that often makes management of issues and such easier. (Same repo would mean needing to tag each issue and each PR with the document to which it applies, and some effort at keeping each confined to one document, rather than logging an issue against both UCR and API and/or submitting a pull request that changes both docs in concert.)

I do think it important that the "use cases that led to what was built" be documented without referring/reading/looking to the API as it stands. Such comparison should happen after the UCR is complete, at that point to confirm whether the API satisfies the UCR or goes beyond it, which extension may or may not be a problem. Such extension beyond the UCR will need to be examined and considered in its own right. (Obviously, if the API doesn't satisfy the UCR, it will then make sense to add features to the API.)

[msporny]

We discussed this on the 2022-04-05 call. @jandrieu provided an update to note that work continues on the use cases document and the expectation is that it will be placed into its own repository after it has been cleaned up.

Next step is to take the current use cases document and convert it into ReSpec, adopt it as a CCG work item (if necessary), and publish as a separate repository.

[jandrieu]

@eric-schuh and I can advance the conversion to ReSpec

[jandrieu]

There is a partial start at https://github.com/w3c-ccg/vc-api-use-cases

[msporny]

The group discussed this on 2022-11-08. Eric noted that conference season has made progress difficult. There are PRs open that need to be reviewed, there is also a PR to fill in the rest of the use cases document. The goal for end of year is to get current PRs accepted and rough draft of full document in outline form with all sections filled in. Next year, sequence diagrams is to do update and get to example URLs that are using in real world.

We are expecting reviews before now and mid-December. We are expecting a complete updated draft of the use cases by the end of the 2022 calendar year.

[msporny]

The group discussed this on the 2023-06-13 telecon. @eric-schuh provided an update and noted that a lot of the use cases have been updated with complete flow diagrams placed into the specification. Currently the use cases are being aligned with the API endpoints in the specification.

@jandrieu noted that there are a number of things that are features that are not well represented yet (exchanger endpoints), so there is another pass that's required to go through the document and see if there are things missing or things that need more coverage.

The group noted that the issue is fairly old and generalized and more specific work needs to be done (for which new, more specific issues should probably be raised in the use cases document: https://w3c-ccg.github.io/vc-api-use-cases/).

This issue is closed and work continues in https://w3c-ccg.github.io/vc-api-use-cases/ .