How to contribute to the docs.

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

371 stars 107 forks source link

How to contribute to the docs. #661

Closed jorgemoralespou closed 8 months ago

jorgemoralespou commented 1 year ago

Describe the problem/challenge you have I was reading the kbld docs and there was something not very clear and @cppforlife asked me to contribute a better explanation. I went ahead and after some search in kbld project I came to understand that the docs are all in this repository. I then tried to find where the specific file to be changed was located, and after a lot of searching got to it https://github.com/carvel-dev/carvel/tree/develop/site/content/kbld/docs and then I didn't know what brancch of the docs to add the contribution, as it's a better explanation of a feature that already exists for a long time. Then I was wondering how I can test the changed docs, but there's no way to know how to test this site locally. So I have given up :-(

Describe the solution you'd like I would like a doc on the docs repo and how to contribute to the docs (and test locally before doing a PR).

Anything else you would like to add: :-(

jonasrosland commented 1 year ago

There are instructions for how to run the site locally and test your docs here: https://github.com/carvel-dev/carvel/tree/develop/site If that needs to be updated, then let us know!

jorgemoralespou commented 1 year ago

That needs to be linked from the main README.md as otherwise, how would one know how to get to that specific folder? I guess that maybe it's obvious for hugo users or for carvel contributors, but not for anyone else.

jonasrosland commented 1 year ago

Sounds like a great idea, what say you @microwavables ?

github-actions[bot] commented 11 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.

a-mccarthy commented 10 months ago

Moving over my comment from the issue i opened, https://github.com/carvel-dev/carvel/issues/683, which is a duplicate of this issue.

Consider updating the contributing guide, https://carvel.dev/shared/docs/latest/contributing/, or the Development guide to include information on contributing to docs. Or make a new page in this section for contributing to docs.

Some things to consider including:

Where the docs and site content is located in the repos
If someone sees an issue in the docs, where should they make the issue? In the main carvel repo, or in the project repo?
Which branch to make changes against. Are contributors expected to update just the development (main) branch, or do they need to update all the versions which are impacted?
What tools and versions are used for the site
Any special instructions for building and local version of the site for development
Any tips or tricks to the website that someone might need to know about when contributing

github-actions[bot] commented 8 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.