-
Notifications
You must be signed in to change notification settings - Fork 15.4k
Restructure/De-duplicate information in Start/Intermediate/Advanced Contributing #19108
Description
Feature request: Restructure/De-duplicate information in Start/Intermediate/Advanced Contributing
Parent issue: #18878
As a part of the parent issue of reducing duplicated content in the Contribute section, this sub-issue restructures the content present in the Start Contributing, Intermediate Contributing, and Advanced Contributing sections.
The proposal is to create pages based on each individual topic, and to move information about what might be good for beginner vs. advanced contributors to the Section landing page.
Why this is needed
Reason 1: Duplication
At a glance, there's duplicate/overlapping topics for reviewing pull requests (1, 2), Submitting pull requests and generally working with Git (1, 2, Proposing improvements/filing bugs (1, 2), and more.
Reason 2: Task orientation over "levels"
The current division of these topics into "Starting", "intermediate" and "advanced" topics is at times (but not always) a bit artificial. There's no actual hard blocks preventing a new contributor from contributing new content, for example.
The new structure would focus the pages on the actual tasks/jobs to be done, and allow the potential contributor to decide for themselves whether or not something is within their skill set. We can provide guidance as to what a good place might be to start, but letting people pick their own adventures is good!
Pages affected
[ ] Start Contributing
[ ] Intermediate Contributing
[ ] Advanced Contributing
Proposed new structure
Note: This is in flux and will likely look a bit different in the final PR. I have a feeling there's a few more topics lurking in these pages that I haven't quite sussed out yet.
Start Contributing
- Suggesting content improvements (how to file an issue)
- Contributing new content (+ blog posts/case studies)
- Reviewing PRs
- PR review for reviewers/approvers (+ issue triaging?)
- Localizing content (move it up in the menu)
- Participating in SIG Docs (moves up)
- Most of the info in Advanced, on subpages as needed.
- Documentation style overview (for now, stays the same – will address in a subsequent issue/pr)
- Reference docs overview (stays the same)
Another modest proposal for discussion: doing a big edit of the Git 101-type content
One major issue with the affected pages is the huge(!) amount of basic instructional content around basic Git/GitHub functionality, like creating pull requests.
I propose that we remove any basic "Git 101" content that doesn't directly relate to Kubernetes documentation processes. Meaning, we assume the user knows how to open a pull request (or link to a great tutorial), but we leave in content around our Prow commands or issue/PR labeling systems. There are tons of great Git tutorials out there, and I don't think we need to hold people's hands as much as we are right now :) WDYT?