Update Carvel's content on carvel.dev (previously Google Season of Docs Proposal 2024 that was NOT submitted)

[microwavables]

Update Carvel’s content on carvel.dev

PLEASE NOTE: This proposal was NOT submitted to Google Season of Docs and therefore will not be funded. We are keeping this issue up in case anyone would like to help us in the community. Mentions of budget, metrics, and GSoD information has been removed.

About Carvel

Carvel was originally initiated at Pivotal (now Broadcom), Carvel was born from Dmitriy Kalinin and Nima Kaviani’s frustration with existing tools to deploy Kubernetes workloads. With a UNIX philosophy in mind, they built k14s (“Kubernetes Tools”) – ytt, kbld, kapp, kwt – as simple and composable tools for application development. Dmitriy and Nima released the tools as they were developed, from fall of 2018 to spring 2019. K14s became popular in June 2019 and were rebranded to Carvel in August 2020. “Carvel” was chosen by the project team because the imagery of workers using the Carvel technique of boat building – where the planks of the hull are laid side-by-side without an overlap to create a smooth surface and a robust frame – reminded them of how their tools can combine with UNIX pipes. Over time, Carvel expanded its toolset, introducing new components such as imgpkg, vendir, kapp-controller, and others, each addressing different aspects of the Kubernetes application lifecycle. 

These tools aimed to simplify tasks like image management, dependency management, and application deployment, empowering users to adopt best practices and improve productivity in Kubernetes environments:

• imgpkg: imgpkg is a tool used for Packaging, Distributing and relocating Kubernetes configurations as OCI Images.

• kbld: kbld is used for building all image associated with provided Kubernetes resources, such as YAML files. It focuses on ensuring reproducibility and consistency across environments.

• kapp: kapp streamlines the deployment process by providing a customizable, declarative approach. It offers features like dependency management, diffing, and automation for Kubernetes resources.

• kapp-controller: kapp-controller extends kapp's capabilities by providing a Kubernetes operator for automating application deployment and lifecycle management based on kapp's principles.

• secretgen-controller: secretgen-controller is a Kubernetes controller for generating and managing secrets across multiple namespaces, improving security, and simplifying secret management.

• vendir: vendir facilitates the vendorization of Kubernetes YAML files by managing dependencies, allowing for better organization and versioning of external resources.

• ytt: is a templating engine for YAML files that simplifies configuration management by providing a way to generate Kubernetes manifests dynamically. It enables parameterization, reuse, and composition of YAML configurations.

There is also Carvel kctrl, which is a CLI tool that helps users to observe and interact with custom resources surfaced by kapp-controller effectively. It also allows package consumers to get up and running with Carvel packages faster.

Since September 2022, Carvel has been a Cloud Native Computing Foundation Sandbox open source software project and is no longer owned by VMware/Broadcom.

The project's commitment to open-source collaboration and community-driven development has led to its adoption by organizations such as Twilio, Red Hat, and Terasky which are looking to standardize their Kubernetes workflows and improve developer efficiency. We have many contributors worldwide and have collaborated directly with other open source projects, such as Operator Framework, to create better software. 

The problem

We significantly improved Carvel's website with the new redesign a while back, and while we have many contributors and users, one of the most common complaints is the lack of information on how to get started using the tools, understanding what Carvel is, and why anyone should use the tools.

As more prospective users who are unfamiliar with any of the tools come to the website, it gets challenging to understand why Carvel exists and what problems it is trying to solve on a higher level. ​​When they see a list of tools on the homepage, it can be a cognitive load to go through each tool and learn about them separately which might discourage them from exploring more.

We also want our users and contributors to have clean paths for discovering what Carvel can do and how they can use and contribute to each tool.

Your project’s scope

The project will:

• Update Carvel.dev’s landing page (Relevant issue: Create "What is Carvel?" page #684)

  • Clear messaging on what Carvel is and what problems it solves.

    • Aside from the brief note on the home page, there is no content that describes WHAT Carvel is, WHY It was created, WHEN to use It, or HOW the tools were created and selected to be part of It.

    • Focus on the why more than the how.

    • It's not possible to discuss each tool and its value individually. So focus on the top 1-3 values.

    • Elaborate on what composable means. Many people may know what we mean by this, but it feels like it's slipping into “jargon/overused” territory. While executing this section, we can discuss with the Technical Writer if this would be best suited to a separate page.

  • Someone new to Carvel needs to learn why it exists and how it can help as an integrated suite.

    • Have a user journey and talk about how Carvel can be used.

  • Have an image to show how all tools are integrated

• Provide documentation for secretgen-controller to be added to the website. (Relevant issue: Add secretgen-controller documentation to the website #754)

  • Currently, secretgen-controller does not have its own landing page while all the other tools do. It only points to the GitHub repo.

• Create a “Getting Started Guide” for each tool (Relevant issue: Improve getting started experience #756

  • There isn’t a clearly labeled “START HERE IF YOU ARE NEW” section for users to know how to get started after they install and this is much needed

  • Add a “What’s next?” section to help readers know some related content after installing or getting started guide

• Update our contributing guide to be more robust (Relevant issue: Update the contributing guide to include more information about contributing #755)

  • We need to update our contributing guide on the website to point to docs that may be relevant to contributing, i.e. proposal template.

• Update our basic install guides for each of the tools

  • Overall the install section of each tool is very bare minimum. Look at Velero, as an example, of how there is much more to installing and using it as outlined. The Contributing portion is also very bare bones. Lots of work can be done here to make the ease of using and contributing to each tool more enticing. https://velero.netlify.app/docs/v1.8/start-contributing/ https://velero.netlify.app/docs/v1.8/basic-install/

Work that is out of scope for this project:

Any website infrastructure work

We have not identified any technical writers for this project. We estimate this project could take up to 6 months to complete.

What skills would a technical writer need to work on this project?

• Must have experience in working or interacting with open source projects.

• Must have experience with GitHub and markdown.

• Must have experience or strong familiarity with Kubernetes.

• Nice to have: programming experience in Go

Timeline

The project will take approximately six months to complete at 15-hours per week. Once the tech writer is hired, we'll spend a month on tech writer orientation and create documentation for each part of the project.

Dates	Action Items
May	Onboarding technical writers, orientation
June	Draft content for the landing page; Ask team and community for feedback. Final edits made by end of June.
July	Create “Getting Started Guides” for each tool; Update contributing guides to be more robust
August	Update Basic Install Guides for each of the tools
September	Provide documentation for secretgen-controller to be added to the website.
October	Close out any loose ends, write blog post describing the work done

Additional Information

Previous experience with technical writers or documentation: 

We received a brief docs review by Abigail McCarthy but have not been able to work on any of the items she highlighted in her assessment. Some of the findings are key issues we want to tackle as part of this proposal.

[himanshuaggar]

Hello @microwavables, I am Interested in working on this, please let me know, how can I contribute to the project for it's success.

[microwavables]

Hi @himanshuaggar, thank you for your interest. Unfortunately, we did not submit this proposal in time and will not be funded to hire anyone to work on it. If you would like to work on it on your own time without compensation then we'd grately appreciate your help. Otherwise, we understand if you cannot work on it without payment.

[MeenuyD]

Hello, @microwavables I would like to work on this issue can you please guide me on that?

[microwavables]

Hi @MeenuyD, thank you for your interest in helping us out with our docs. @a-mccarthy will be creating sub issues for each of the items above. Can you review the items and let us know if there's anything in particular you'd be most excited to work on / have the most experience to help with? In the meantime, I encourage you to get familiar with all of the carvel tools, if you haven't already.

[a-mccarthy]

@microwavables, I've created some sub-issues for talking about this work in more detail.

• Create "What is Carvel?" page #684
• Add secretgen-controller documentation to the website #754
• Update the contributing guide to include more information about contributing #755
• Improve getting started experience #756

If are reading along on this issue and are interested in helping with the work outlined, please review the sub-issues for more details and added your feedback there.