Improve and clarify l10n onboarding documentation

[jimangel]

Better late than never 😃

From our discussions about l10n onboarding, @Bradamant3 volunteered to help clarify the requirements that needed to be met for l10n. The intent is to set requirements that encourage the most successful launch and support of new localization efforts.

The original thoughts were:

• requiring that "two contributors" must be new have advanced fluency.
• adding "5 content PRs" in addition to the minimum-required-content
  • deprecation warning should be one of those docs, done via the toml short codes under "deprecation_warning"
  • The toml short codes are already mentioned, it just needs to be clarified to include the warning.

Pages to update:
https://kubernetes.io/docs/contribute/localization/

/assign @Bradamant3
/cc @zacharysarah @kbarnard10

[sftim]

/priority important-longterm

[sftim]

requiring that the "two contributors" must be new

It sounds like this would block a localization proposal where one existing contributor pairs with a new contributor to start a localization. Have I misunderstood? I don't think I follow the reasoning.

[zacharysarah]

I don't think they need to be new, but they do both need to have advanced fluency.

[jimangel]

I updated the issue, but I'm not sure how we can gauge fluency? Honor system?

[sftim]

It looks like #16965 landed in master without passing the criteria in this issue.

[remyleone]

I don't think it is a good idea to add friction and extra steps to prevent an init localization PR to start. My input would be to have a minimal PR that gives an initial team as much autonomy as possible to start working. I really don't see how adding extra requirements will help. I think a CNCF action to talk at a meetup is way more efficient to gather additional contributors rather than rising up the admission bar.

See also https://rfc.zeromq.org/spec:42/C4/

[sftim]

I like the idea of small changes, iteration, and frequent merges; as an IT consultant, it's a way of working that I encourage colleagues and customers to adopt.
It must be frustrating to work on a branch and not see the changes go live until the minimal (as in, current documentation) localization is done. The Russian localization took about 2 months from opening a PR to publication, and I'm really glad that lots of people put in the effort that they did.

I suppose that for me the downside / drawback to having localization published very early is what to do if or when a particular effort does not really go anywhere.

So I'm wondering, what is the impact if there are some poor quality localizations? For example, there are three that are disabled at the moment, I think that is because those did not seem to meet a quality threshold.

I'm really fine with the idea of starting a localization effort. Publishing to the live site affects readers, search engines, people's bookmarks and so on. So I'm also worried about the cost of sometimes having to disable a localization, like the three that already ended up in that state.

I can see an argument for waiting for a localization to meet that quality threshold before publishing it; it feels odd to publish docs that aren't good enough on the expectation that soon they will be.

---

So, with that said, this feels like something we can discuss again at a SIG Docs meeting. @remyleone would you like to put this down as a future agenda item? If not, I can bring the topic up and point to the discussion in this issue.

[jimangel]

I don't think it is a good idea to add friction and extra steps to prevent an init localization

Just to be clear @remyleone, this issue was never opened with the goal of making it harder for localization. It is a lot of effort to localize these docs (as you are very well aware of 🙏) and in the past we've spent much of our contributors time getting new teams setup - only to find the content is deactivated, under maintained, or we lose contributors (circumstances / life).

As a result of increasing the requirements for a localization, we are encouraging a larger sustainable team. The whole intent is for successful localization with a clear pathway that is sustainable.

I would second @sftim's advice that this can be better discussed in a meeting setting. I am open to alternatives that still align with our main goal / intent.

[remyleone]

I don't see any impact on poor quality localizations. Search engines won't bring them up in the first place because no other pages will link to them if their quality is poor. Same for bookmarks.
If pages are not viewed maybe it is a sign that the CNCF should motivate people to open meetups and recruit new contributors/students that are willing to participate in those languages.

I think discussions about the localization and decisions about it should include a lot of people that actually do the localization. I think any decisions that affect them or other potential contributors performing similar tasks should include their voice.

[jimangel]

100% agree about getting all stakeholders involved.

[zacharysarah]

deprecation warning should be one of those docs, done via the toml short codes under "deprecation_warning"

I agree about not per se raising barriers to localization, but this should absolutely be included in the minimum requirements, given its outsized impact and the potential for localization teams to use the shortcode to indicate which version is in fact the most current for that language.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[sftim]

/remove-lifecycle stale

[sftim]

Did the meeting about this reach a conclusion about n content PRs? (for example: is n = 5?)

[zacharysarah]

@jimangel Do you remember what we discussed? I’m fine with 5, even understanding that it may be 5 l10n PRs that aren’t published yet.

[sftim]

5 PRs opened? That's a good clarification.

[jimangel]

@zacharysarah @sftim I believe it was just any content beyond the required content. Good with 5 opened PRs.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[jimangel]

Given the staleness / lack of understanding I think this is safe to close...
/close

[k8s-ci-robot]

@jimangel: Closing this issue.

In response to this:

Given the staleness / lack of understanding I think this is safe to close...
/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.