search

carvel-dev / carvel

Carvel provides a set of reliable, single-purpose, composable tools that aid in your application building, configuration, and deployment to Kubernetes. This repo contains information regarding the Carvel open-source community.
https://carvel.dev/
Apache License 2.0
375 stars 115 forks source link

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

Open microwavables opened 6 months ago

microwavables commented 6 months ago

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:

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:

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?

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 commented 5 months ago

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 commented 5 months ago

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 commented 5 months ago

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

microwavables commented 5 months ago

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 commented 5 months ago

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

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.

microwavables commented 5 months ago

@a-mccarthy I've added the relevant issues into the issue above :)

microwavables commented 5 months ago

@MeenuyD The items have been updated with relevant sub-issues. Let us know if there are any you're excited to work on!

MeenuyD commented 5 months ago

Thank you for creating a sub-issue I am particularly interested first in contributing to the "What is Carvel" page as part of the Carvel documentation project. I would greatly appreciate any feedback you have on the content of the blog post that I have written here is the link (https://meenuy.hashnode.dev/carvel-tools-simplifying-kubernetes-application-deployment) I have not included the demo in the blog I will write another blog for that.

github-actions[bot] commented 4 months ago

This issue is being marked as stale due to a long period of inactivity and will be closed in 5 days if there is no response.

github-actions[bot] commented 2 months ago

This issue is being marked as stale due to a long period of inactivity and will be closed in 5 days if there is no response.

microwavables commented 2 months ago

@praveenrewar this was auto-closed, wanted to make sure that was intentional, otherwise, recommend re-opening! :)

praveenrewar commented 2 months ago

Thank you @microwavables!! I had added the carvel-accepted label but forgot to remove the carvel-triage label so it still got marked as stale.

github-actions[bot] commented 3 weeks ago

This issue is being marked as stale due to a long period of inactivity and will be closed in 5 days if there is no response.