Skip to content

Umbrella Issue: Clean up duplicate content in Contribute section #18878

@celestehorgan

Description

@celestehorgan

This is a Feature Request

In preparation for a more in-depth re-organization of this section, I want to
clean up any duplicate or almost-duplicate content under https://kubernetes.io/docs/contribute/start/. This will make further re-organization less problematic, particularly for downstream
parts of the docs process like translations, as content will only be
in one 'place'.

A good example of near-duplicate content in this section is the following:

In this case, it's better to choose one "review pull requests" as the source and just
link to it from the other section. This reduces the amount of content we need to maintain
and makes sure inaccuracies that can creep in over time are easier to keep track of, because
they're all in one place.

Somewhat related but I'd also love to do a sweep for general grammar/sentence structure
in this section while I'm at it.

I (@celestehorgan) will be executing on this issue as a nice
intro task to my new job as a tech writer here at CNCF, with @zacharysarah as support :)
(Hello everyone! I'm here to add tech writing capacity to CNCF projects!)

Why is this needed

  • This is a good-sized intro task for a career tech writer, and I need to ramp up before I can contribute to k8s and other CNCF projects in a more meaningful way.
  • Duplicate content is difficult to maintain in the long-run and confusing for the user.
  • Getting rid of duplicate content facilitates re-organizing the section.
  • A grammar edit is never a bad idea.

Follow-on effects

  • Translations will need to be updated in quick succession. The next step in this
    process is to take the edited content and rearrange it in a more user-friendly,
    sustainable fashion, and if translation doesn't take these changes quickly
    it could make any reorganization of topics in future very difficult for them to
    follow. This needs to be done step by step.

Lazy Consensus

This issue proposes lazy consensus. For lazy consensus, this issue needs:
[ ] Agreement from the current translation teams to mirror the work done on this task
as soon as possible after.

I'm not sure what else this might need – feel free to suggest something, @zacharysarah :)

Assuming the following precondition is met, lazy conensus will be the following:
[ ] @celestehorgan removes duplicate content and edits the existing english language content

I'd love comments and suggestions, as this is my first major contribution to the community.

Related issues:

#18920 (closed)
#19108 (open)

Metadata

Metadata

Assignees

Labels

sig/docsCategorizes an issue or PR as relevant to SIG Docs.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions