Google Season of Docs: project proposal #677
Description
Project: Fill in missing docs content by adapting the CNB technical specification for buildpacks.io
About Cloud Native Buildpacks
Cloud Native Buildpacks (CNBs) transform your application source code into container images that can run on any cloud. With buildpacks, organizations can concentrate the knowledge of container build best practices within a specialized team, instead of having application developers across the organization individually maintain their own Dockerfiles. This makes it easier to know what is inside application images, enforce security and compliance requirements, and perform upgrades with minimal effort and intervention. The CNB project was initiated by Pivotal and Heroku in January 2018 and joined the Cloud Native Computing Foundation (CNCF) as an Apache-2.0 licensed project in October 2018. It is currently an incubating project within the CNCF.
The CNB project maintains a set of specifications and tooling (1, 2, 3) that make it possible to write buildpacks and orchestrate them together in a build system. Our community includes multiple (and sometimes overlapping) personas, including:
- Application developers, who write source code that needs packaging into a container image,
- Buildpack authors, who write buildpacks according to the Buildpack Interface Specification, and
- Platform operators, who implement and maintain build systems that use buildpacks according to the Platform Interface Specification.
About the docs project
The CNB project maintains a specification that defines the contract that buildpacks, platforms, and a component called the lifecycle are expected to observe when builds are executed. Unfortunately, this specification is (by design) written in dry, technical language, and is intended for consumption by readers already familiar with CNB concepts and internal architecture. Additionally, the content is grouped together such that different personas (such as an application developer or platform operator) may struggle to find the content that is most relevant for them.
The project recently completed a reorganization of our documentation website to make it easier to determine where docs content should go. The content was divided first by persona (app developer, platform operator, buildpack author), and further separated by content type (tutorials, concepts, and how-to guides, according to the Divio docs model). During this process, we identified a significant amount of missing content - CNB features and concepts that are detailed in the technical specification, but are not covered on the website nor presented in a manner that is tailored to the personas for whom they are relevant.
Project scope
As part of this project, the technical writer will:
- Spend some time with our existing documentation website to get to know buildpacks and the needs, concerns, and workflows of the different personas.
- Become familiar with the CNB specification (both Buildpack and Platform) on GitHub to determine the relevant persona for each content section, and if it is currently documented on the website.
- For example, each entry in CNB terminology should have a page under “concepts” for the relevant persona; each entry in Data Format should have a “how-to” guide explaining when and how to create or use the file; and so on.
- Where content is missing, create a placeholder page and corresponding GitHub issue to document what needs to be added (and where, linking to the placeholder page if possible).
- Fill in missing content as needed and as time allows. The content should include:
- A plain language description of the concept or feature,
- Links to other relevant documentation or content,
- Diagrams (where appropriate) to facilitate understanding,
- Code snippets (where appropriate) to demonstrate example use.
Work that is out of scope for this project:
- Updates to samples and tutorials. We expect the work to be mostly confined to adding “concepts” and “how-to” -style content.
- Stylistic or cosmetic changes to existing content.
- Further organizational changes beyond what has already been achieved via the recent reorganization.
We are currently inviting technical writers to apply for this project, and we estimate that this work will take six months to complete. The project will be supported by our Learning Team Lead @AidanDelaney, our Implementation Team Lead @natalieparellano, and our community manager @microwavables.
Measuring our success
In our most recent user survey, “better documentation” was the most highly requested planned feature by far, with 28/50 respondents (56%) indicating it is a priority for them. Free-form comments included sentiments such as “[the] documentation is very poor” and “I have had to look through the code to figure out what is happening”. A follow-up survey about our documentation after completion of the project would give some indication of how well we did.
Additionally, we will keep track of the number of Slack inquiries that we are able to address with a link to our existing documentation (vs a link to the spec). In the past 3 months, 12 of our community conversations in the #buildpacks channel have included links to buildpacks.io, whereas 6 have included links to the spec repo on GitHub. We aim to proportionally increase the number of conversations that are addressable with links to buildpacks.io.
Finally, we will track the number of GitHub issues (corresponding to placeholder pages where missing content has been identified) that are opened and closed throughout the period, with a tentative goal of over 45 issues (15 pieces of missing content added per persona).
Timeline
We estimate that this work will take six months to complete.
| Dates | Tasks |
|---|---|
| May | Project familiarization (go through existing documentation to understand personas) |
| May-June | Review buildpack spec through the lens of a buildpack author to identify and fill in missing content on docs website |
| July-August | Review platform spec through the lens of a platform operator to identify and fill in missing content on docs website |
| September-October | With learnings from buildpack and platform specs, enumerate buildpacks features and the subset of concepts that are relevant to app developers; identify and fill in missing content on docs website |
| November | Finalize project, gather community feedback |
Project budget
| Budget item | Amount |
|---|---|
| Technical writer review existing content, identify missing content, and create new content for documentation website | 8000.00 |
| T-shirts (10, various sizes) | 250.00 |
We are fortunate to have a number of contributors and maintainers who are willing to dedicate their time to this effort and/or are paid to work on the CNB project.
Additional information
Our existing contributors and maintainers actively contribute to the documentation website. We use the hugo framework which is relatively simple and intuitive and mostly involves working in markdown. There are a few stylistic and procedural conventions that we use (such as page titles and content summaries) that can be readily explained and documented.
Several of our contributors and maintainers, including project supporters @AidanDelaney and @natalieparellano, have participated in Google Summer of Code and/or LFX mentorships in the past, successfully guiding mentees to completion of their projects. From this we have learned the importance of setting clear expectations, having open lines of communication and regular check-ins, and exchanging feedback early and often. We are excited to bring these learnings to Google Season of Docs.
How do I get started?
If you are a technical writer interested in applying for this project, please:
- We've created an application form to help us gather all the details from those that are interested in taking on the role of technical writer for the project. Please fill this out by 8:00am Pacific Time, Monday, April 22.
- Reach out to us in the #buildpacks-learning-team channel on CNCF Slack with any questions
- Spend some time getting to know buildpacks by reviewing our documentation website and the tutorials for each persona
- It is helpful to have some experience working with container technologies such as Docker, or systems that run container images (such as CI/CD)