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

Refactor docs #296

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
291 changes: 291 additions & 0 deletions text/0000-re-org-docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,291 @@
# Meta
[meta]: #meta
- Name: Reorganize docs website
- Start Date: (fill in today's date: 2023-09-20)
- Author(s): natalieparellano
- Status: Draft <!-- Acceptable values: Draft, Approved, On Hold, Superseded -->
- 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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An example sidebar could look like:

Screenshot 2023-10-30 at 11 00 36 AM

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this. It's much more straightforward than what I was thinking and thus more achievable.


# 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
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
│ │ ├── 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
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
│ ├── 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
│ │ └── use-tooling
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
│ │ ├── 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
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
│ ├── 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.
natalieparellano marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also potentially breaks SEO and links to the documentation outside of us. Will we redirect to the homepage or other pages?


# 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

<!--
## Amended
### Meta
[meta-1]: #meta-1
- Name: (fill in the amendment name: Variable Rename)
- Start Date: (fill in today's date: YYYY-MM-DD)
- Author(s): (Github usernames)
- Amendment Pull Request: (leave blank)

### Summary

A brief description of the changes.

### Motivation

Why was this amendment necessary?
--->
Loading