Provide user documentation for cocina models

[justinlittman]

This would be intended for internal non-dev users and external users interested in cocina.

[justinlittman]

Here is the current rendering of the openapi.yml: http://sul-dlss.github.io/cocina-models/

[andrewjbtw]

Questions I think external users are going to have, based on questions that I have had in the past or still have:

• What are the things being managed here? Are the three types of thing the "DRO", "Collection", "AdminPolicy"? How are they related?
• What is a DRO?
• What's the difference between a DRO and a "Request DRO"?
• What's an AdminPolicy? - yes, I realize this is more a question about Stanford's repo design rather than Cocina
• What's required for each type of thing? (i.e. what's the minimum required to make a DRO/collection/AdminPolicy)
• What's the difference between "validate", "validate a request [thing]", and "validate a [thing] with object metadata"?
• What exactly is "object metadata"?

[justinlittman]

One possible approach is to have an overview page that addresses some of these questions and points to specific parts of the published (rendered) openapi documentation. This will allow identifying the schemas that are relevant to a user (DRO, Collection, AdminPolicy) while avoiding those that are not (ObjectMetadata).

I also wonder if there isn't a different rendering that provides better access to the schemas ("DRO") instead of the endpoints ("validate a ...").

[justinlittman]

To reduce the confusion over "validate ...", those labels can just be changed to whatever is clearest -- they serve no real function in cocina.

[justinlittman]

Also, redoc supports a variety of configuration options: https://redocly.com/docs/api-reference-docs/configuration/