Call for feedback: Paketo Documentation

[fg-j]

I'd like to gather some feedback about the current state of the Paketo documentation and discuss potential improvements. Feedback on the content of the docs, the organization of the docs, and the discoverability of the docs are especially important.

To survey the current state of Paketo docs, you can look at:

1. the Paketo site
2. the READMEs of composite buildpacks (e.g. https://github.com/paketo-buildpacks/go)
3. the READMEs of implementation buildpacks (e.g. https://github.com/paketo-buildpacks/go-build)
4. (to some extent) godoc for Paketo packages (e.g. https://pkg.go.dev/github.com/paketo-community/cpython)

I'm hoping to start a discussion here about:

1. What works/doesn't work about the current documentation for buildpacks users
2. What works/doesn't work about the documentation process for contributors to our documentation (this includes Paketo maintainers)
3. Examples of other projects whose documentation we think is exemplary in some way. Link to the docs you like and why you think they're good
4. Ways the Paketo documentation could be improved

This asynchronous discussion will be followed up with a chat in the Paketo Working Group meeting on 4/20/21. You can learn more about the Paketo Working Group meetings here.

[sophiewigmore]

[Paketo site]
I noticed that the buildpacks.io docs have search functionality now. It's really helpful, and I'd love to see something like that implemented on our website, due to enormous amount of information we have in our docs.

[ryanmoran]

Looks like it is provided by https://www.algolia.com/.

[dmikusa]

I often get confused as to whether some bit of info I want is in the Paketo docs or if it's in the Buildpacks.io docs. I know they are separate and there's a technical distinction, my brain hasn't adjusted to this or I just have bad luck, cause I invariably end up looking through both sites before I find what I want.

If the Paketo site gets search and it could also return search results for buildpacks.io, that would be super helpful, IMHO.

[sophiewigmore]

[READMEs]
A major issue I have as a contributor is that our READMEs across repositories are different. I struggle to know when I should update the README or just update the docs. I would love to decide on a specific format and sections for the READMEs so that they are easier to navigate for users as well.

[fg-j]

Perhaps a template would be helpful. Or even a script that generates a nice README based on some structured input.

[dmikusa]

+1 for automation that generates a standard format README. The buildpack.toml has a good amount of what usually ends up in the README, or at least the parts that change and need updated like version numbers, config settings, default values, etc...

[fg-j]

Ahh, you're talking about the things in the [[metadata]] sections of the Java buildpack.tomls, right?
(e.g. https://github.com/paketo-buildpacks/bellsoft-liberica/blob/main/buildpack.toml)

I agree this could be a good source of (at least some of) the structured information to go in a README.

[dmikusa]

[READMEs]

I think the READMEs for composite buildpacks should have a quick start/usage example at the top. When someone goes to the README, there's a good chance they want to know how to use it. We should make sure that the README addresses this.

My $0.02 would be to include a short section at the top of every composite buildpack README, that has an appropriate pack build command to run build an image. Then link to the docs where they can find a more detailed example & configuration reference.

[dmikusa]

[READMEs]

For the implementation buildpacks, I think we should have a redirect towards the top that points to the composite buildpack. If you are new and come to one of the implementation buildpacks, you see the usage section and it's not clear what you should do. It looks like you should run this script, but then what?

A note at the top to the effect of "If you are trying to build an application, you probably want the XYZ CNB instead." & possibly a short explanation that this buildpack is only one part of a functioning buildpack group, would help to redirect users to where most users need to be.

[kvedurmu]

I'd like to give some more thought into the general information architecture of our language family buildpack docs (e.g https://paketo.io/docs/buildpacks/language-family-buildpacks/dotnet-core/). It would be interesting to think of this from the perspective of a new developer, coming in with very little understanding of buildpacks (maybe they heard about it in a blog post and want to try it out to see how it compares to Dockerfiles). To me, all of the language family documentation should be broken down to follow along this new developer's journey with Paketo.

For every language family, this might look something like:

101 level (basic configuration information and usage)
This to me should be at the very top of any docs page and contain any information pertaining any configuration users can set. If I have an app that builds with an existing Dockerfile but fails with Paketo, the first place I would want to be directed to is a configuration section on a given docs page because it is likely that I am just forgetting to set an environment variable (or some other configuration). So, some things we'd want to document here:

• Usage. It would be nice to be able to see some terminal output for how to be able to build a sample app for the language family across various platforms. So, something like a tab view for common CNB platforms (pack, kpack, Spring Boot, etc.)
• what dependencies are supported?
• Environment variables that I can set to configure the buildpack (e.g BP_NODE_VERSION) or any documentation that indicates that the buildpack respects the corresponding configuration supported by the language family (e.g setting a .nvmrc file). To me, I just want to see a single buildpack-supported way to set this configuration so we should remove things like buildpack.yml references because it feels like unnecessary if we actually want users to move towards environment variables. Note - buildpack-set environment variables would not be under this.
• Setting common image configuration (Procfiles, CA Cert, etc.). This should eventually just be a link to https://paketo.io/docs/buildpacks/configuration/#types-of-configuration.

201 level (more "advanced" buildpack configuration)
This is more specific to the Java buildpack documentation, but there is a lot of more advanced configuration currently scattered around that makes it hard to follow the docs sometime. An example of this might be "Connecting to an APM", "Enabling JMX", etc. that users likely will not need until their app is successfully building.

301 level (visibility/transparency into the build process)
I see this section providing any visibility into the magic behind our buildpacks. The content should be geared towards users that are already familiar with buildpack that might want to learn more about the internals and/or possibly contribute a change. Some things I'd expect to be documented here

• Buildpack-set environment variables
• Explanation of installation process, caching etc. This table is a great example of this - https://paketo.io/docs/buildpacks/language-family-buildpacks/nodejs/#npm-installation-process
• Component buildpacks in a given language family. E.g https://paketo.io/docs/buildpacks/language-family-buildpacks/java/#components

[kvedurmu]

One note - some of our buildpacks are pretty close to having a flow like what i've outlined (e.g .NET Core docs). It's just a matter of figuring out how to make these docs less verbose and that would be a big improvement.

[ryanmoran]

I think including a laundry list of possible configuration options as 101 documentation might be a bit daunting for a new user. Wouldn't we want to start with more general use-case information walking through the general set of features?

[emmjohnson]

One thing I find difficult about the docs on paketio.io, is that the table of contents is embedded at the top of the page instead of on the side bar. It would be nice if the side bar was static and only the content of the docs scrolled.