kubernetes / kubernetes/website

Simplify the contribution guidelines

Open
#28,573 10 comments 0 reactions 0 assignees View on GitHub
kind/feature lifecycle/frozen priority/important-longterm sig/contributor-experience triage/accepted
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

The current contribution guideline is too wordy to contributors, old and new. As a reviewer myself, I have a difficult time to find out a guideline when attempting to quote it or refer a contributor to it. For example,

- We are not accepting "dual-hosted" or "3rd party" contents, where are those guide?
- We don't fix blog pages that are over 12 months old, where exactly is this mentioned?

If I just started reading the contribution guides, there are so many pages. The left hand navigator has no logic in it. The fonts are almost the same size. We have for "writing new topic" and "contributing new content", we have "reviewing changes" and "participating in SIG Docs", we have "Custom Hugo Shortcodes" and "advanced contributions", "content guide" listed alongside "content organization" and "page content types" ...

Let's consider how to tailor and reorganize this. Contributing to k8s docs should not be so difficult as it smells today.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the contribution-guide pages, the left-hand navigator, and the sections named in the issue, including content guidance, organization, page content types, and Hugo shortcodes. Done means the contribution guidance is reorganized into a clearer, less verbose structure and explicitly covers the rules cited in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
hugo
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.