Skip to content

Restructure/De-duplicate information in Start/Intermediate/Advanced Contributing #19108

@celestehorgan

Description

@celestehorgan

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?

Metadata

Metadata

Assignees

Labels

priority/important-longtermImportant over the long term, but may not be staffed and/or may need multiple releases to complete.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions