diff --git a/text/0656-re-org-docs.md b/text/0656-re-org-docs.md new file mode 100644 index 000000000..de5e9df30 --- /dev/null +++ b/text/0656-re-org-docs.md @@ -0,0 +1,291 @@ +# Meta +[meta]: #meta +- Name: Reorganize docs website +- Start Date: 2024-02-08 +- Author(s): natalieparellano +- Status: Approved +- RFC Pull Request: (leave blank) +- CNB Pull Request: (leave blank) +- CNB Issue: (leave blank) +- Supersedes: N/A + +# Summary +[summary]: #summary + +This RFC proposes reorganizing the docs website according to CNB personas and the "four quadrants of docs" aka the [Divio documentation system](https://documentation.divio.com/structure.html). + +# Definitions +[definitions]: #definitions + +* Personas - people with different roles who interact with the CNB project in different ways + * Buildpack Authors - write buildpacks + * App Developers - use buildpacks + * Platform Operators - orchestrate buildpacks builds + * ... +* Four quadrants + * Tutorials - from Divio: `lessons that take the reader by the hand through a series of steps to complete a project of some kind` + * Oriented toward beginners + * Should be tested to make sure they work + * Explanations - from Divio: `discussion [that] clarify and illuminate a particular topic` + * Theoretical knowledge + * How-to guides - from Divio: `take the reader through the steps required to solve a real-world problem` + * Practical knowledge + * Reference - from Divio: `technical descriptions of the machinery and how to operate it` (similar to CNB spec) + * Technical knowledge + +# Motivation +[motivation]: #motivation + +- Why should we do this? + - Our docs website is a bit disorganized - it's hard to find stuff, and it's hard to add stuff. Consequently, the content of our docs is woefully incomplete. +- What is the expected outcome? + - Our docs website will be easier to use for everyone. Eventually, the content of our docs will become more complete as it's easier to add stuff. + +# What it is +[what-it-is]: #what-it-is + +This provides a high level overview of the feature. + +- Define the target persona: all personas, including project contributors, can benefit from this. +- Explaining the feature largely in terms of examples. + - See the example [branch](https://github.com/buildpacks/docs/tree/refactor) of github.com/buildpacks/docs and abbreviated tree with notes below. + +# How it Works +[how-it-works]: #how-it-works + +``` +. +├── for-app-developers +│ ├── concepts +│ │ ├── builder.md <- NOTE: missing content! +│ │ ├── oci-image.md <- NOTE: missing content! +│ │ ├── platform.md <- NOTE: missing content! +│ │ └── project-descriptor.md <- NOTE: missing content! +│ ├── how-to-guides +│ │ ├── configure-build-env.md +│ │ ├── declare-source-metadata.md +│ │ ├── download-sbom.md +│ │ ├── export-to-oci-layout.md +│ │ ├── mount-volumes.md +│ │ ├── specify-buildpacks.md +│ │ ├── specify-extensions.md +│ │ ├── specify-processes.md +│ │ ├── understand-failures.md <- NOTE: missing content! +│ │ ├── use-cache-image.md +│ │ ├── use-http-proxy.md +│ │ ├── use-inline-buildpacks.md +│ │ └── use-project-descriptor.md +│ └── tutorials +│ ├── advanced-build +│ │ ├── build-for-arm.md +│ │ ├── build-for-windows.md +│ │ ├── build-on-podman.md +│ │ └── reproducibility.md +│ └── basic-build +│ ├── basic-build.md +│ └── build-phases.md +├── for-buildpack-authors +│ ├── concepts +│ │ ├── build-plan.md <- NOTE: missing content! +│ │ ├── buildpack.md +│ │ ├── component-buildpack.md <- NOTE: missing content! +│ │ ├── extension.md +│ │ ├── group.md <- NOTE: missing content! +│ │ ├── layer.md <- NOTE: missing content! +│ │ ├── package.md +│ │ ├── sbom.md <- NOTE: missing content! +│ │ └── targets.md <- NOTE: missing content! +│ ├── how-to-guides +│ │ ├── migrate <- NOTE: moved from the "reference" section +│ │ │ └── deprecated +│ │ │ ├── buildpack-api-0.4-0.5.md +│ │ │ ├── buildpack-api-0.5-0.6.md +│ │ │ └── buildpack-api-0.6-0.7.md +│ │ │ ├── buildpack-api-0.7-0.8.md +│ │ │ ├── buildpack-api-0.8-0.9.md +│ │ │ └── buildpack-api-0.9-0.10.md +│ │ ├── package-buildpack +│ │ │ ├── buildpack-toml.md +│ │ │ ├── package-buildpack.md +│ │ │ ├── specify-targets.md +│ │ │ └── with-clear-env.md <- NOTE: missing content! +│ │ ├── publish-buildpack +│ │ │ ├── publish-a-buildpack.md +│ │ │ └── publishing-with-github-actions.md +│ │ ├── write-buildpack +│ │ │ ├── add-labels.md <- NOTE: missing content! +│ │ │ ├── add-sbom.md +│ │ │ ├── create-layer.md +│ │ │ ├── defer-plan-entries.md <- NOTE: missing content! +│ │ │ ├── re-use-layers.md <- NOTE: missing content! +│ │ │ ├── specify-env +│ │ │ │ ├── add-to-posix-paths.md <- NOTE: missing content! +│ │ │ │ ├── for-build.md <- NOTE: missing content! +│ │ │ │ ├── for-process.md <- NOTE: missing content! +│ │ │ │ ├── for-run.md <- NOTE: missing content! +│ │ │ │ └── with-modifier.md <- NOTE: missing content! +│ │ │ ├── specify-processes.md +│ │ │ ├── specify-slices.md <- NOTE: missing content! +│ │ │ └── verify-targets.md +│ │ └── write-extension +│ │ └── advanced-extensions.md +│ └── tutorials <- NOTE: this would be the ruby buildpack where you have to keep updating the script every time +│ ├── advanced-buildpack +│ │ ├── build-plan.md +│ │ ├── caching.md +│ │ ├── exec-d.md <- NOTE: missing content! +│ │ ├── layer-types.md +│ │ └── processes.md +│ ├── basic-buildpack +│ │ ├── build.md +│ │ ├── building-blocks-cnb.md +│ │ ├── detection.md +│ │ └── local-env.md +│ └── basic-extension +│ ├── build-dockerfile.md +│ ├── building-blocks-extension.md +│ ├── run-dockerfile-extend.md +│ ├── run-dockerfile-switch.md +│ ├── setup-local-environment.md +│ └── why-dockerfiles.md +├── for-platform-operators +│ ├── concepts +│ │ ├── builder +│ │ │ ├── base-images +│ │ │ │ ├── base-images.md +│ │ │ │ ├── build.md +│ │ │ │ └── run.md +│ │ │ ├── builder.md +│ │ │ ├── buildpacks +│ │ │ │ ├── buildpack.md +│ │ │ │ ├── group.md +│ │ │ │ └── order.md +│ │ │ ├── create-builder.svg +│ │ │ ├── extensions +│ │ │ │ └── extensions.md +│ │ │ ├── lifecycle +│ │ │ │ ├── _index.md +│ │ │ │ ├── analyze.md +│ │ │ │ ├── build.md +│ │ │ │ ├── create.md +│ │ │ │ ├── detect.md +│ │ │ │ ├── export.md +│ │ │ │ ├── launch.md +│ │ │ │ ├── rebase.md +│ │ │ │ └── restore.md +│ │ │ └── metadata +│ │ ├── operations +│ │ │ ├── _index.md +│ │ │ ├── build.md +│ │ │ ├── build.svg +│ │ │ ├── rebase.md +│ │ │ └── rebase.svg +│ │ └── platform.md +│ ├── how-to-guides +│ │ ├── create-a-builder.md +│ │ ├── create-a-stack.md +│ │ ├── migrate +│ │ │ ├── _index.md +│ │ │ ├── deprecated +│ │ │ │ ├── platform-api-0.3-0.4.md +│ │ │ │ ├── platform-api-0.4-0.5.md +│ │ │ │ ├── platform-api-0.5-0.6.md +│ │ │ │ └── platform-api-0.6-0.7.md +│ │ │ ├── platform-api-0.10-0.11.md +│ │ │ ├── platform-api-0.11-0.12.md +│ │ │ ├── platform-api-0.7-0.8.md +│ │ │ ├── platform-api-0.8-0.9.md +│ │ │ └── platform-api-0.9-0.10.md +│ │ ├── specify-extensions.md +│ │ └── integrate-ci +│ │ ├── circleci.md +│ │ ├── gitlab.md +│ │ ├── kpack.md +│ │ ├── pack +│ │ │ ├── cli +│ │ │ └── concepts +│ │ │ └── trusted_builders.md +│ │ ├── piper.md +│ │ └── tekton.md +│ └── tutorials <- NOTE: we should add stuff here +└── reference <- NOTE: we should keep this content as lean as possible and link back to the spec where we can, as it tends to get out of date +│ ├── config +│ │ ├── builder-config.md +│ │ ├── package-config.md +│ │ └── project-descriptor.md +│ └── spec +│ │ ├── buildpack-api.md +│ │ ├── distribution-api.md +│ │ └── platform-api.md +``` + +# Migration +[migration]: #migration + +A lot of content would be moving from the buildpack tutorial to the buildpack how-to section. +The current buildpack tutorial has the end-user make a `ruby` buildpack by editing the same file over and over. +It is good for teaching but hard to explain advanced concepts like multiple processes, SBOM, etc. +We should break the advanced concepts out of the tutorial and link back to the samples (or just give short code snippets) instead. + +As suggested by @AidanDelaney, we should consider changing the tutorial to make a `nodejs` buildpack: + +> The current example installs the runtime, installs the package manager, and resolves the packages. Could we simply install a nodejs runtime and build a vanilla application? + +We should make these changes in one huge PR. We should NOT attempt to redirect from old links as that would be too hard. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? +- It's a lot of work +- Changing the structure of the docs could be surprising for users who are already familiar with its content + +# Alternatives +[alternatives]: #alternatives + +- What other designs have been considered? + - Do nothing +- Why is this proposal the best? + - Easier to find stuff + - Easier to add stuff + +# Prior Art +[prior-art]: #prior-art + +See https://documentation.divio.com/adoption.html + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- What parts of the design do you expect to be resolved before this gets merged? + - The general structure in the tree above +- What parts of the design do you expect to be resolved through implementation of the feature? + - Edits to individual pages +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? + - ??? + +# Spec. Changes (OPTIONAL) +[spec-changes]: #spec-changes + +N/A + +# History +[history]: #history + +