[Tracking Issue] Revamping the Contributor Guide

[mrbobbytables]

xref: kubernetes/contributor-site#86

A large portion of the contributor site is based on the presenting the Contributor Guide in a more web-presentable/user-friendly way.

The current README and organization structure of docs should be updated to accommodate this other method of presentation. What this entails is the README becoming more of "landing page" and steering folks to specific sections as quickly as possible.

Currently identified tasks include:

• Update and break apart the README to steer people to areas. The other sections should become their own doc or consolidated into another one.
• Titles and weights within the header metadata should be updated to better reflect their purpose.
• Remove outdated components of the contributor guide
• Document and consolidate overlapping areas of the contributor guide
• Additional description field added to header metadata for auto-ToC generation under docsy

Nice to have bonus items:

• Collect Information on the gaps identified by new contributors going through the guide.
• Update the docs with the previously identified gaps.
• Reorganize guide targeting two contributor persona types: new and current

---

/area contributor-guide
/sig contributor-experience
/priority important-soon

/cc @markyjackson-taulia @parispittman
/assign @vishakhanihore @castrojo

[vishakhanihore]

@mrbobbytables I had something else in mind , What about creating a custom landing page in hugo for the contributor section and then guiding them to the other section of our contribution guide ?
I have roughly four subsection as of now in my mind:

• Getting started with Kubernetes.
• Making your first contribution.
• Communication & Meetup.
• Policies, Procedure & Documents.

This will be better for a newbie or an experienced contributor to surface the stuff according to needs.
Also such task-based navigation may give a better look to website like other contributors websites have.
cc: @markyjackson-taulia @parispittman

[mrbobbytables]

I would lean towards that being called something like 'getting started' instead of guide. We want to surface both the contributor and developer guide to the site eventually so they're indexed well. We have a big discovery problem with our documentation and getting them on a site outside of GitHub will do much for that.

[vishakhanihore]

I would lean towards that being called something like 'getting started' instead of guide. We want to surface both the contributor and developer guide to the site eventually so they're indexed well. We have a big discovery problem with our documentation and getting them on a site outside of GitHub will do much for that.

Yes, I totally understand, Rendering the content out of the original repository is already too much. But a contributor website with just markdown and documentation may be a little bore ?

[mrbobbytables]

Yes, I totally understand, Rendering the content out of the original repository is already too much. But a contributor website with just markdown and documentation may be a little bore ?

I think there's room for both. We need our docs to be more discoverable (searchable). They aren't in their current state and that's a problem.

Long term the full blown developer guide should be synced over there as well.

EDIT: As an example. The python developer docs: https://devguide.python.org/
It's 'boring', but sooo incredibly useful. This information isn't surfaced well currently and it needs to be.

[mrbobbytables]

/unassign @vishakhanihore
/help

[k8s-ci-robot]

@mrbobbytables:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/unassign @vishakhanihore
/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[mrbobbytables]

At this point in time the big priority is removing / updating inaccurate information from the guide. A few examples include:
The old collaboration doc: #4866
The bug bounty program: #4865

Both of these contained inaccurate information and the canonical source of truth was in other docs.

[mrbobbytables]

Collection of little notes on dupes etc.

• contributing.md and getting-started.md have a lot of overlap
• commit message guidelines / code review covered
  • contributing.md
  • pull-requests.md
  • review-guidelines.md