# Common Docs on the Carvel Website
See [this issue for the _why_](https://github.com/vmware-tanzu/carvel/issues/58) of this proposal.

PRs:
- ~~https://github.com/vmware-tanzu/carvel/pull/544~~
- ~~https://github.com/vmware-tanzu/carvel/pull/545~~

## Terminology
- **common doc**: documentation that is the same or similar across subprojects (such as "How to Contribute").
- **micro-site**: a subproject's website (example: https://carvel.dev/ytt/).

## Goals
1. Make common docs **easily discoverable** for the users.
2. Make common docs **maintainable** for the maintainers.
3. Deliverable by September 9 for the CNCF Sandbox Review.

## Proposal
1. Single source of truth for all common docs live on the website.
- Each micro-site has the following links in their docs:
- Contributing
- Code of Conduct
- Security Policy
- Development Guidelines
- These all link to the same common doc.
- example: https://carvel.dev/shared/docs/latest/security-policy/
- All GitHub repo "placeholder markdown" files (e.g. CODE_OF_CONDUCT.md) link to the common doc on the website.
- [_Cutting this scope for now since it requires additional structural changes_] For Development Guidelines, we need to incorporate tool-specific guidance (e.g. https://github.com/vmware-tanzu/carvel-kapp-controller/blob/develop/docs/dev.md)?
- We could have a Development Guide section with two links: `Developing <subproject>` and `Carvel Development Guidelines` (common doc)
1. Introduce a dropdown option on the main website to navigate to the common docs
- add `Project Docs` to Projects dropdown

### Cut from scope
1. A solution for cross-tool documentation (such as guides). Currently, we don't have this content. Right now, our best option is to use micro-sites and blog posts.

## Research from other projects

### [Argo](https://argoproj.github.io/)
- They have 4 subprojects. This feels like a familiar separation of subprojects as Carvel.
- The four subprojects are listed across the top of the landing page.
- Each subproject has its own landing page. This landing page provides high-level information and then directs to a documentation-specific site (e.g. https://argoproj.github.io/workflows/).
- The `Get Started` call-to-action (CTA) leads to a subproject's Getting Started page.
- Each subproject's documentation-specific site has its own listing for common documentation. There is not any common documentation that is shared between the projects.
- Each subproject's documentation-specific site has certain topics:
- Overview (Home)
- Getting Started
- Concepts
- Installation
- FAQ
- Security (which lead to github repo)
- Developer Guide / How to Contribute
- Releases (just links to github)
- Roadmap
- Blog (this is shared across subprojects)
- There are some topics that could be useful but are not present on all subprojects:
- Understand the Basics (links to build up a fundamental understanding of the underlying technologies (e.g. kubernetes, kustomize, helm))
- User Guide
- Operator Manual
- Tutorials

Pros:
- Clean landing pages. Docs complexity is contained to docs-specific sites.
- Clear boundaries. Each subproject is responsible for its own docs only.

Cons:
- There is not a direct way to navigate between subprojects. The best way is to go back to the main project page.
- Minimal overlap of docs means more to maintain.

?:
- Not sure how they handle subprojects that have overlap in their workflows.

### [Flux](https://fluxcd.io/)
- They have a landing page with a lot of info on it. Clear CTA for getting started.
- Though flux is a toolkit, the components all seem to be similar (i.e. controllers).
- They have a dropdown for common documentation that's present at all times (under Project).
- Their docs are mostly shared. Flux and Flagger have separate docs-specific sites.
- There are dropdowns to dig into Guides, Use Cases, Migrations, Toolkit Components, Toolkit Dev Guides, CLI.

Pros:
- It's easy enough to navigate around the site.

Cons:
-