Umbrella Issue: Clean up duplicate content in Contribute section

[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:

• https://kubernetes.io/docs/contribute/intermediate/#review-pull-requests and
• https://kubernetes.io/docs/contribute/start/#review-docs-pull-requests

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)

[remyleone]

👍 Welcome, @celestehorgan I think this is a good idea. A lot of content in the contributor's pages is indeed duplicated. Also, pages are very long so consider splitting them into thematic one. It would be easier for the different localization teams to work on them.

[celestehorgan]

@remyleone The general tactic I'm taking is clean up the content in place first (this issue), let the translation teams catch up, then move around the content and break them out into different sections second (a yet-to-be-created issue).

The reasoning for this is that if I did both steps at once, from the perspective of a potential translator a rearranged and edited page of content would look.. almost like an entirely new page altogether, generating more translation work than actually needs to occur.

[zacharysarah]

@celestehorgan I know we talked about this earlier in video chat, but the more I think about it, the more my thoughts have evolved.

The general tactic I'm taking is clean up the content in place first (this issue), let the translation teams catch up, then move around the content and break them out into different sections second (a yet-to-be-created issue).

It's safe to both de-dupe and refactor content simultaneously. But see below--

The reasoning for this is that if I did both steps at once, from the perspective of a potential translator a rearranged and edited page of content would look.. almost like an entirely new page altogether, generating more translation work than actually needs to occur.

Kudos for empathy! 💛 That said, localization teams use a script to diff content changes, so there's no artificial need to separate de-duplication and refactoring into discrete tasks.

That said, it's good practice to open one issue per task. For example: one issue for de-duplicating content, one issue for refactoring content. You could close both issues with a single PR that did both--but that's not really best practice, either.

TL,DR

It may make sense from a workflow perspective to de-dupe and refactor as separate tasks, but there's no hard requirement to keep them separate. At the same time, it's good to isolate concerns to one problem per issue and one fix per PR.

Long story short, do what seems best!

[sftim]

/sig docs
(why not?)

[celestehorgan]

/assign @celestehorgan

[celestehorgan]

I'm treating this as an umbrella issue, because it's going to make PR review more manageable. That said, the easiest way for me to piecemeal this work out is to make issues as I go along :)

First issue: #18919

[celestehorgan]

Update: The next sub-issue: #19108

[zacharysarah]

@celestehorgan With #19576 merged, I think we can close this. 🎉

/close

[k8s-ci-robot]

@zacharysarah: Closing this issue.

In response to this:

@celestehorgan With #19576 merged, I think we can close this. 🎉

/close

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.