Problems caused by the same weight values of some pages

[bconfiden2]

This is a Bug Report

Problem:
Some pages at the same width have the same weight in their _index.md.

Originally, the pages have to be sorted based on weights even when localizing the documents.

However, for some pages with the same weight at the same level, they are sorted in the order of the strings of the translated titles, which makes them out of order with the English documents.

Each localization teams might change the weight according to their language and put them in the right order,
but I think it would be better to change the overall weights in the English document.

And more than 100 pages need to be modified.

For example in Korean, the pages are sorted by first letter of "Korean-translated title", the order of pages below in Korean is different with that of English.

• English
  

• Korean
  

Proposed Solution:
Re-order every page that has the same weight in the same level.

Page to Update:

If you guys think this is needed, I will organize all the pages that need to be modified at the comment.

I have structured the pages of the whole document like below.
Pairs with the same weights are marked with [ N ] at the beginning of the title.
The value at the end of the title is each of their weights.

/kind cleanup
/assign

[sftim]

Given how much this is a problem for localizations, we could (should?) add a CI test to warn when two pages have an equal weight in a section - that'd be a way to stop the problem returning.

I presume that pages with no weight declared are also a problem for the same reason.

[bconfiden2]

Thank you for comment @sftim, and add as a CI test seems good idea!

But before adding, wouldn't it be better to check it once and make changes, and then add this task to a CI test? 😃

As you commented, there were some pages that had no weights, too!

[sftim]

wouldn't it be better to check it once and make changes, and then add this task to a CI test?

I'm OK with either order. Folks can work on the CI test first, or the manual fix first. We'll only really get value if we do both of those things (otherwise, we'll tend to find that we return to a state where page weights overlap).

Another fix might be to sort localized pages with overlapping weight based on the collation order of the English equivalent page. That does not sound easy, mind!

[bconfiden2]

Neither do I think it's not easy to change the weights according to each Localizations.
That's why I opened an issue for English documentation!!

Would it be better to open a PR first(with personally modified wieghts) and then get a review,
or would it be better to agree on the appropriate weights here first??

[a-mccarthy]

Thank you @bconfiden2 for bringing this up in the localization meeting yesterday! After chatting about it in the meeting, we determined, based on the research done by @bconfiden2, there aren't any sections where overlapping page weights are causing a different ordered side navigation in localized content that will disrupt users from understanding content. Meaning, there aren't any sections in the side nav where this issue is occurring and a user would need to read the pages in a specific order.

Our recommended action is:

1. Raise this as an issue within the broader sig docs community, in slack and in the next community meeting, to make sure folks working on the English language docs understand the importance of page weights and potential problem overlapping pages weights cause in localized content.

2. Use a "lazy" updating approach, to adjust English language page weights as a page is updated. I think if we implemented @sftim's idea for adding a CI warning that would help speed up making the adjustments to each English page.

3. We may also want to add a note to our Page Order docs to highlight that we shouldn't use overlapping weights within a section.

@bconfiden2 and @seokho-son does this sound like a good summary of our discussion? Did i miss anything?

cc: @bradtopol

[bconfiden2]

Thank you for your opinion @a-mccarthy !! 😃 😃

I also agree that each localization teams would be nice to aware of this even if it doesn't need to be modified now!
For Page Order docs, it seems great idea, and I'll open an issue for that!

[seokho-son]

/triage accepted

[sftim]

/area localization

[sftim]

Watch out for updating the weight values for pages that are autogenerated - we should teach the page generator to produce our preferred values instead.

[k8s-ci-robot]

@sftim: Reopened this issue.

In response to this:

/reopen

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.

[a-mccarthy]

During the docs sprint we were tracking the areas that we already checked for page weights issues in this Hack MD file: https://hackmd.io/VtoYICL6SnGaL_QaySrbcw?view. Pages that have been checked off on the list were reviewed or a PR was opened to address the issue. Anything left unchecked still needs to be be reviewed and possibly updated. Note, the reference docs are mostly autogenerated and do not need to be updated.

[a-mccarthy]

/reopen

[k8s-ci-robot]

@a-mccarthy: Reopened this issue.

In response to this:

/reopen

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.

[a-mccarthy]

I've reviewed the hackmd file and it looks like the only section of the docs that hasn't been reviewed is the https://github.com/kubernetes/website/tree/main/content/en/docs/tasks section. There is a PR open that addresses the page weights of _index.md files for the folders in the Tasks section, #37481. But there has not been a review for any of the pages within any of the folders.

This is a rather large section of the docs and will definitely need to have page weights adjusted in some areas.

[seokho-son]

Hi @bconfiden2

If you guys think this is needed, I will organize all the pages that need to be modified at the comment.

I have structured the pages of the whole document like below.
Pairs with the same weights are marked with [ N ] at the beginning of the title.
The value at the end of the title is each of their weights.

Do you have a script to check the current weights ? if then, I think we could check remaining tasks for this issue. :)

[bconfiden2]

Yes I have, but the script is not clean at all. 😅 😅
If you need it immediately, I can upload(or send) the script right now.
If not, I'll send it to you after refactoring.

[seokho-son]

@bconfiden2
It is just for checking remaining tasks :) no need to hurry :)

[a-mccarthy]

I've been working on making PRs to finish this issue up. The largest section left to do is the Tasks section. I plan to have PRs to cover those updates this week. Sorry i've left off wrapping this up for so long, but hopefully we can get all the page weights updated in english soon

[seokho-son]

I think we've made enough effort to arrange the page weights. Even though there is a possibility a few pages are not updated correctly, I think we can assume it can be caught by additional issues.
So, I am going to close this issue as completed.

Feel free to reopen this issue if necessary.

/close

[k8s-ci-robot]

@seokho-son: Closing this issue.

In response to this:

I think we've made enough effort to arrange the page weights. Even though there is a possibility a few pages are not updated correctly, I think we can assume it can be caught by additional issues.
So, I am going to close this issue as completed.

Feel free to reopen this issue if necessary.

/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.