Cluster-api: Revisit documentation structure

[rbitia]

Goals

1. Take a second look at the Cluster API book documentation and how it relates to specific provider documentation
2. Re-visit documentation depending on findings of goal 1 and re-structure documentation.

Non-Goals/Future Work

1. Re-writing documentation

User Story

As a new user of Cluster API, I wasn't sure how to create a management cluster to then get started with the cluster api book instructions. I'm also not sure why or how to pick a cloud provider.

Detailed Description

I would like us to do a comprehensive review of how the docs are structured today while also understanding where new users would probably land in the documentation. For example a new user of cluster API might not understand that one management cluster maps to one cloud provider when landing in the cluster api book documentation. We also need to make sure wherever we want new users to land is actually where they end up, by making the getting started kind of docs as accessible as possible. We also need to consider that we have 2 places where documentation lives, in provider documentation and the cluster api book, there might be room for consolidation here.

/kind proposal

[elmiko]

adding a comment here as i am interested in refactoring the docker provider documentation and i think the work would be congruent with this effort.

i would like to contribute a documentation change that removes the docker information from quickstart and adds(or improves) the separate developer-facing docs about docker.

i have consulted with at least one other community member who would like to contribute, i think we have good coverage for Linux targets.

anyways, just wanted to join the conversation, appreciate any feedback =)

[rbitia]

I've been thinking about this more, I think we should use the Cluster API book for all documentation including provider specific documentation. We can have separate tabs or sections for each provider. That way we can lean on each other for doc structure but we also have a one stop shop for all documentation for users. The opposite of this would be splitting out the docs (including the quick-start) into each provider's repo which I think would cause more friction and the docs would be unruly. What do folks think about that approach? If we get a consensus I'm happy to take a stab at creating a structure..

[CecileRobertMichon]

+1 from me, user docs being centralized in one place makes a lot of sense.

I think the only docs that might still live in provider specific repos are development stuff specific to the repo (like how to use make targets to run unit tests, e2e tests, etc).

[detiber]

+1 from me as well for centralizing docs.

I would like to see us find a way to organize the per-provider docs in a way that we can leverage separate OWNERS files to make it easier for provider maintainers to contribute and update the docs, though.

[elmiko]

+1 @rbitia , i like this idea as well.

I would like to see us find a way to organize the per-provider docs in a way that we can leverage separate OWNERS files to make it easier for provider maintainers to contribute and update the docs, though.

just to be slightly contrarian, what about the notion of having the individual provider repos maintain their own docs with the publish process being able to pull them in from a config list?

i only propose this to hopefully allow wider inclusion of provider types without necessarily needing to do a large amount of configuration on this repo. just a thought =)

[alexander-hughes]

As a new member to the CAPI community I had a lot of difficulty in setting up my first dev environment. To be fair I have limited experience with the projects that CAPI leverages in the quick start.

I put together a blog post on the Airship website with how I accomplished a dev environment setup with help from @elmiko that may be helpful in the documentation re-structuring.

[vincepri]

/kind documentation

[rbitia]

Cool so a couple things we want to do initially:

• Allow providers to PR docs into their respective repos and use a config file to build docs from providers to the CAPI Book
• Create a separate section within the CAPI Book for providers, and create common doc structures for common docs like machine pool support, networking & more... We want the docs to be similar in structure for easy usability across providers.

I'm wondering if we can get a doc writer from the CNCF to help us out? I'd be willing to work closely with them! To do so the maintainers of CAPI would need to email the cncf service desk asking for support.

[elmiko]

Cool so a couple things we want to do initially:

* Allow providers to PR docs into their respective repos and use a config file to build docs from providers to the CAPI Book

* Create a separate section within the CAPI Book for providers, and create common doc structures for common docs like machine pool support, networking & more... We want the docs to be similar in structure for easy usability across providers.

++, i like both of those ideas

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[CecileRobertMichon]

/assign
/ifecycle active

[vincepri]

/remove-lifecycle stale

[vincepri]

/priority backlog

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fabriziopandini]

/remove-lifecycle stale

[vincepri]

/lifecycle frozen