Glossary edit, perhaps a cosmetic one

I was just looking at the Glossary and noticed that it wasn't alphabetized correctly; see image.

Someone might want to fix that and put the "Certificate issuer" term in its correct spot in alphabetical order.

4 Likes

It might be put there based on the "issuer" part. Just guessing here. If it indeed was intentionally put there, it might be reasonable to put a link to the actual position at the "C" position.

2 Likes

True... and to rewrite it to be "Issuer of certificate" isn't the correct term. Maybe call it "Issuer" and then put (a.k.a. Certificate issuer)?

2 Likes

I dunno, I suggest we wait until someone comes along who knows if it's correctly or incorrectly placed in the first place :stuck_out_tongue:

3 Likes

Shall we begin a countdown of how many days it takes someone to acknowledge this suggestion? :wink:

3 Likes

If it's the intention that the glossary should be alphabetized (I'm not sure that it is, @tdelmas?), then there's a few other items which should be reordered as well

Anybody is free to submit a PR against website/content/en/docs/glossary.md at master · letsencrypt/website · GitHub, with care to relocate the entries in all 8 localizations.

4 Likes

Thanks for the ping @_az

It's supposed to be in alphabetical order. I think it's because it was "issuer" before, and not reordered when renamed! Feel free to open a PR :wink:

Also, now that I think about it, the translations will never be in the correct order, I'll need to improve the macros... Handle alphabetical order in the translation of the Glossary · Issue #1194 · letsencrypt/website · GitHub

5 Likes

That would require I learn how to use GitHub and I'm not a programmer! How easy is GH to learn how to use?

3 Likes

Barring some git specific terminology you might not be familiar with such as PR (Pull Request), no programming or git skills should be required (unless you want to actually learn git a bit). The files you would be requesting changes on are plain text files with some minor markup (the format is actually called Markdown and is designed to be human readable even as plain text). Once you have an account, it's possible to submit the changes entirely using the web-based editor Github provides. Though I'm not sure how easy it is with the web-based editor to group multiple changes into a single pull request.

Conceptually, a pull request works like this:

  • You create a copy (aka "Fork") of the repository (the collection of files that make up the website) on your own Github account.
  • You modify the files that need fixing in your fork and commit (save) them to your repository
  • You create a pull request against the original respository with your changes. That process is essentially asking the owners of the repository to pull in the changes from your repository (at which point they can review and approve, deny, or request additional changes).
  • If the PR is approved, the commits in your fork get added as commits in the original repository (with your Github identity listed as the author).

Then the next time Let's Encrypt updates the website with the files from their repository your changes will be live for all to see.

Once you have a Github account, go to the page for the file you want to edit and click the pencil icon (edit). Github will automatically make the fork of the repository on your account and put you into a web-based editor for that file. Make your changes, add a commit message in the form at the bottom, and click the Propose Changes button.

8 Likes

Those are awesome instructions and an awesome overview, thank you.

So what's the etiquette around here regarding submitting PR requests? Az says that if you're making a PR against a website doc, it also has to be similarly edited in the localized version; I assume that means pinging @tdelmas to let him know that you've made one?

5 Likes

I should add that even if you don't want to be the one that actually submits the changes. Even just submitting an issue is helpful so that the owners of the repository can track the problem and fix it themselves.

6 Likes

So Site Feeback can go here in this forum and also submitted as an issue to the GH? Is one preferred over the other?

2 Likes

Generally speaking, submitting an issue is usually considered polite before opening a pull request with the fix(es). It gives the owners a chance to discuss the problem with you before you spend the time working on the fix. But since that discussion has already largely happened here on the community forums, no one would likely fault you for going straight to the PR (and the PR itself can also end up being a discussion thread within Github).

I'll defer to the repository owners as to which location they prefer feedback to source from. But the fact that there's a dedicated category for Site Feedback here makes me think either is fine. It can be nice to add a link from the Github issue to the discussion here (and vice-versa) so that people can follow the conversation wherever it ends up.

You shouldn't need to explicitly ping anyone here about an issue/PR you've made on Github. The built-in notification features should take care of that for you.

7 Likes

I've been told in the past NOT to touch any translations when submitting a PR and offering to translate into any of the languages I know.

IIRC, the rationale: the translations all have a "last modified" field at the top, and that is used to determine how out-of-date the content is. Updating the date can suggest an out-of-date file is in sync; not updating the date can cause issues for the translators who have to figure out why the file's modified date and 'last modified' payload are out of sync. Perhaps that changed.

5 Likes

You're correct.

When you open a Pull Request to propose some changes, there are two possibilities:

  • Your changes impact the content/meaning of the text, thus translations must be updated. In that case, lastmod must be updated, that way, the old translation will display a message saying that the translation is not "up to date", and someone will upload the English version to Crowdin, to have them updated.
  • Your change only impact the English version, for example, to fix a spelling mistake, or in this case, to fix the alphabetical order. Translations do not need to be updated, so lastmod must not be updated. Nothing else to do
7 Likes

Thanks for sharing those tips @tdelmas! :+1: And it occurs to me that the alphabetical order would be different in every language anyhow. :slight_smile:

6 Likes

Yes... I've opened an issue about it

I've a solution in mind, I will try to test it in the next few days

7 Likes

I've open a PR to fix the issue in all languages (including English): Sort Glossary by tdelmas · Pull Request #1195 · letsencrypt/website · GitHub

Result in English: Glossary - Let's Encrypt - Free SSL/TLS Certificates

Could someone check if those languages are correctly sorted ? I'm using Hugo's GetSortedMapValues but I'm not sure how well it works with languages other than English.

Hebrew: מונחון - Let's Encrypt - Free SSL/TLS Certificates

Chinese: 术语表 - Let's Encrypt - 免费的SSL/TLS证书 and 術語表 - Let's Encrypt - 免費的 SSL/TLS 憑證

7 Likes

I can confirm that the Hebrew glossary is correctly sorted. (I only checked the order of the initial letters, not the order within a single starting letter, but the fact that the order of the initial letters is correct is a good sign.) I also ran Unix sort on this file (under a U.S. English locale, so collation is being done just using Unicode character order). This gave almost no changes from your version except that my sort wanted to sort מ later than ם, because the Unicode value of מ is higher than that of ם, even though I think this is an error because these characters should be treated identically for collation purposes.

6 Likes

Thanks. So I think this PR is a good first step in the right direction.

@tlrenkensebastian no need to propose a Fix for the English version, the proposed fix Sort Glossary by tdelmas · Pull Request #1195 · letsencrypt/website · GitHub will sort all languages including English!

7 Likes