Re-worked definitions for v2 of the platform wg glossary

[earth2marsh]

Addresses #485.

Thanks to @abangser , @joshgav , @ebcarty , and @kurktchiev for all their contributions!

[netlify]

✅ Deploy Preview for tag-app-delivery canceled.

Name	Link
🔨 Latest commit	9f62918
🔍 Latest deploy log	https://app.netlify.com/sites/tag-app-delivery/deploys/65d522469b98250008e47d4a

[abangser]

Love this! Thanks so much for all your hard work @earth2marsh. In particular I appreciate having the clear headings for each item.

One thing we need to confirm is if/where we need to do translations for this file. Sorry I didn't think of it sooner, but I suspect this is a copy paste job into the 3 other languages we have in the site. I have set request changes for this review but I personally think we should add this at the end once we have approval for the English version rather than needing to change in multiple places as reviews come in 👍

[earth2marsh]

That makes sense to me, thanks. I agree we should focus on closing out the English version first before investing time in translations.

As for the question of when/if, I'm not familiar with the organization's policy here, but I hope others on this review will know! Looking now through the current version 1 of the glossary, it seems that the:

• Chinese version has been translated
• Korean version has only headings translated
• Japanese version has not been translated.

If I've understand that correctly, it suggests to me that we might publish English versions in the shorter term and update each translation as we are able over time?

[abangser]

Yup, that is the list I was thinking of Marsh. I do think we can tackle the merging of translations once we settle on English, but if translations are not updated on merge, we still want to keep them sensible so I believe we have at least two options:

1. Revert back to english for the language
2. Leave the existing translation with a note suggesting checking the English page for an updated version.

This is pointing us towards needing version the glossary directory. That would allow all languages, including English, to retain history. With versioning, my vote would be to do the 2nd option within this PR for any page with translations (Chinese and Korean) and update to English for others (Japanese).

I would then suggest that the version 2 update translations be handled in other PRs but I think it is helpful to give people a heads up and see if they have any ideas / preferences as I don't have experience translating myself.

My understanding is the following people may have an interest in the following languages:

• Chinese version has been translated: @node, @windsonsea, @rootsongjc, @mouuii, @mengjiao-liu, @cubxxw
• Korean version has only headings translated: @Eeap, @sysnet4admin, @seokho-son
• Japanese version has not been translated: @hhiroshell, @kaitoii11, @MasayaAoyama, @naonishijima

Just to say, This is a lot of names and I don't know how we want to handle this in the future and we have a number of things we need to tackle, ideally in an traceable way.

So in summery my suggestion is:

• Update this PR to introduce the concept of versioning to the Glossary page (@earth2marsh and I am happy to help)
• Keep the comments / suggestions in the PR focused on the content of the Glossary update in English
• Conversations about who and how to alert on translation update needs would be best suited for Suggestions for Introducing a GitHub Action to Improve the i18n Workflow #537 where we are trying to find a light weight solution that works for everyone
• Translation updates to v2 of the glossary are encouraged to confirm this version is approved before tackling and then to open a new PR using the translation template (and giving feedback on if it helps or hurts the process!)

This is all just a suggestion though, and as we evolve on #537 we will learn so please do improve this workflow with us!

[dstengle]

@earth2marsh Sorry for coming so late to the game, but maybe it would be possible to introduce some more of the ecosystem element to the glossary? Right now the terms point to a patform team in a more monolithic sense when in reality there may be a number of platform providers and consumers in an organization where a consumer could be an end user or another platform provider.

I think "Team" is often used flexibly to represent up to larger organizations but the distinction might be useful here and it still aligns well with other things mentioned, including team topologies.

[earth2marsh]

@dstengle I think that is worth considering for v3 of the glossary. The v2 goal was to clean up and reorganize the v1 document in light of the maturity model work, and to make sure the terms defined in the glossary support the two published papers. If there is specific language you'd like to suggest, there's a Google doc linked in issue #485 that you can comment directly within. FWIW, I do think there is more we can do to highlight that multiple platforms will likely exist in any org of sufficient size, and that different people in different roles/teams may be consuming or producing or both.

[joshgav]

Thanks @earth2marsh for your work here and @abangser for all your support. I agree that we should edit English first then reflect changes to other languages. Also, as @abangser suggested, let's think about implementing versioning for the glossary, perhaps in the same way we've implemented it for the maturity model and whitepaper, e.g. here: https://github.com/cncf/tag-app-delivery/tree/main/platforms-whitepaper. We can open a new issue to introduce that versioning system for the glossary.

[joshgav]

Thank you for driving this work @earth2marsh! LGTM.

[abangser]

Given the open issues for translations, let's get this merged and we can do the improvement work to site structure soon!

Fantastic work @earth2marsh and team 👏👏👏

[indyaah]

Hi folks, first of all apologies for a drive by comment from an onlooker. I have been following TAG from the sidelines for internal advocacy purposes.

The change introduces duplicative entries for TVP, is that intentional and something that would be cleaned up in a follow up work?

[joshgav]

Thank you @indyaah for catching that! I was able to quickly edit and remove the old TVP section right here in the GitHub interface. Before I merge though, could someone please double-check again that everything is good? Thanks @earth2marsh @abangser @roberthstrand !

[abangser]

@joshgav I can't seem to see the new preview deploy, but absolutely can confirm the duplicate and that you're delete looks good in the diff.

Great catch and quick fix!

[earth2marsh]

Thanks @indyaah for catching that.

@joshgav your edit LGTM. However, platform users was also duplicated, so I've removed that as well. I think this is now good to go!

[joshgav]

Okay, thanks everyone! Let's merge and we'll continue to iterate together!