Self-contained documentation for bundles

[radu-matei]

https://github.com/deislabs/duffle/pull/509 was an initial attempt to have something close to self-contained documentation for bundles. Essentially, it relied on a file inside the invocation image that got read and displayed on the console for a Duffle command (docs).

The case for self-contained documentation -- take the case of container images -- you have one place where you learn about the image -- the registry, then you go to the terminal and pull the image, then you go back to the registry to find out where the source code and documentation are, so you know how to use the image.

We could avoid doing this with bundles by having the bundle and docs in the same place -- ideally in the bundle file.

A couple of thoughts related to this:

• use the description, or documentation fields in bundle.json to hold such info.

• there are going to be multiple tools interacting with the bundle -- some with output on the console (Duffle, Docker App, Porter), some with an HTML renderer (VS Code extensions, web pages). Should we allow multiple versions for this in the bundle, and each tool can choose which one to use based on its capabilities?

• should there be another field for a URL with more documentation?

• should we reserve the docs/ directory in the invocation image for documentation? If so, how would someone actually interact and read the docs? (there are various technical solutions -- from copying the entire directory locally, and using the user's default text editor, to opening a console file explorer inside the invocation image) -- the question is how should the user experience be in such scenario?

Thoughts? Thanks!

[garethr]

I've been thinking a little about this as well and had a few related conversations, including with @lucperkins, who wrote https://medium.com/@lperkins/the-state-of-docker-container-documentation-some-workarounds-and-a-vision-for-a-possible-future-693d6ca5baaf

My take:

• A description field is necessary but not sufficient for documentation purposes I feel. It acts as a useful summary, but cramming all docs in a single fields feels limiting.
• You could provide a reference, ie. a documentation URL. The issue with that on the surface is that isn't self-contained, however it could be useful at build time to save docs. I'd argue this doesn't need to be in the spec
• I'm +1 on reserving /docs for documentation purposes, but a number of questions come up:

1. Should the spec say anything about file formats for documentation?
2. Should the spec say anything about file names for files in the /docs folder?
3. Should there be a default entrypoint, ala README in GitHub

I think they are the only questions we need to answer in the context of the spec. When it comes to how tools choose to build a user interface on top of that, that's the individual tools concern. If we don't say anything about these questions then it's easier to see in incompatibilities between tools. So my take:

1. Yes, but we don't need to mandate actual formats to use. We should just say that files must have extensions to indicate format
2. Yes, that files with the same name but different extensions are equivalent - ie. README.md, README.html, README.txt
3. Yes, lets stick with README as it's widely supported by other tools

I think that would allow clients to expose the docs and for tools to build suitable experiences on top of that data.

[technosophos]

I suppose another approach would be to define another action (io.cnab.docs) that was responsible for printing documentation from the bundle in some standard format. Then we could leave the actual implementation as an exercise for the reader (or, rather, bundle author).

[garethr]

We discussed this on the community call on the 27th of February. One additional point was viewing this from the registry side.

Having documentation available to registries would be a useful property of this, and exposing this as an action would mean registries would need to run the action, which may not be a safe operation and is costly in terms of compute requirements. A standard action is still useful for easy access by some clients but as a higher level API in addition to the lower level one.

The discussion moved to docs as part of the file system. @SteveLasker suggested in the OCI implementation storing the docs directory as a separate layer, with relevant metadata and type information. This is a general problem for other artefact types, and solving generically is useful.

This is additive to what we have now, so the only change to the core spec is to reserve the docs (or other) filesystem location. Docs would then get an optional section of the spec which answers the above questions. We would need to work out where the registry/OCI image part of that lives, either with the rest of the documentation details or as part of the WIP OCI part of the spec.

[SteveLasker]

I loved this idea as it solves the problem of artifacts (images, CNAB, Helm, ...) to keep their docs in sync between their git repo, the registry listing and the artifact itself. To kick off an OCI conversation, I started the discussion in the new OCI Artifact Registry slack channel: https://opencontainers.slack.com/archives/CGJFFCPS7/p1551292629007000 To get access, you can get an invite here: https://chat.opencontainers.org/