Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Limit CNAB references throughout documentation #175

Closed
carolynvs opened this issue Feb 20, 2019 · 2 comments · Fixed by #3200
Closed

Limit CNAB references throughout documentation #175

carolynvs opened this issue Feb 20, 2019 · 2 comments · Fixed by #3200
Assignees
Labels
docs Markdown ahoy! Updates needed on porter.sh or in dev docs.

Comments

@carolynvs
Copy link
Member

It's a bit confusing right now how we talk about CNAB, the spec, how porter maps back to it, etc in our docs right now. Because we can't make assumptions about what people know, and if people are coming to a page because they want to know about a porter feature or because they want to know about how porter is conforming to the spec.

I spoke with @jeremyrickard and we agreed on how to organize the docs a bit:

  • Add a page explaining CNAB and how porter uses it
  • Add a page explaining how the manifest maps to a bundle.json, where we conform to the spec and where we have unique features/data
  • On each page, call out interesting CNAB tidbits in a subsection titled CNAB.
  • Don't start any doc with references to CNAB, or assume that the reader already knows what it is. Assume that each porter doc (and the reader) is there for the porter feature first.
@carolynvs carolynvs added the docs Markdown ahoy! Updates needed on porter.sh or in dev docs. label Feb 20, 2019
@carolynvs carolynvs assigned carolynvs and unassigned carolynvs Feb 20, 2019
@carolynvs carolynvs added this to the CNAB 1.0 milestone Jun 27, 2019
@carolynvs carolynvs removed the backlog label Sep 14, 2019
@carolynvs carolynvs removed this from the CNAB 1.0 milestone Mar 4, 2020
@carolynvs
Copy link
Member Author

New plan: We still need 1 page that explains CNAB, but otherwise unless its clearly relevant we no longer want to try to point out how everything relates back to CNAB. At this point it's just an implementation detail.

@carolynvs carolynvs changed the title Organize CNAB explanations in our docs Limit CNAB references throughout documentation Mar 11, 2022
@carolynvs
Copy link
Member Author

I still want to do a sweep so that we don't use mixed terminology for things like invocation images (cnab) vs bundle image (porter).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Markdown ahoy! Updates needed on porter.sh or in dev docs.
Projects
Development

Successfully merging a pull request may close this issue.

4 participants