[doc] Revise the glossary documentation

[tengqm]

What changes were proposed in this pull request?

This PR fixes the glossary docs.

Why are the changes needed?

The glossary is reordered for quick reference.

Does this PR introduce any user-facing change?

No.

How was this patch tested?

N/A

[justinmclean]

Please do not break sentences over multiple lines as this breaks some tooling.

[tengqm]

Please do not break sentences over multiple lines as this breaks some tooling.

No. I don't agree with this. Long lines are hard to review, hard to maintain, hard to read even in an IDE.

[justinmclean]

IDE wrap lines, so that's not really an issue. As I explained elsewhere, if you break up lines, tools like grammar and style checkers that we use will not work. Some people who contribute to this project don't have English as their first language and rely heavily on these tools.

[tengqm]

IDE wrap lines, so that's not really an issue. As I explained elsewhere, if you break up lines, tools like grammar and style checkers that we use will not work. Some people who contribute to this project don't have English as their first language and rely heavily on these tools.

No. It is an issue, and a very annoying issue. Please refer this comment.
Different people (including developers) see different things (I'm not using your IDE),
that is an additional issue. This is like the TAB usage scenario.
Grammar or style checker is not a valid reason for this change.
I was not encouraging breaking a long line in the middle.
I was suggesting to break long lines APPROPRIATELY, at statement boundary, at punctuation.

[tengqm]

Check this change and tell me ... how this change is breaking your IDE syntax checker?
Can you elaborate how this "line breaks" hurts anything?

[justinmclean]

That change is fine. The issue occurs when you break up a sentence over several lines.

[justinmclean]

Changes like this cause the issue:

[tengqm]

Okay, let me revise this further. Breaking those long sentences to simple English.

[jerryshao]

@justinmclean would you please help to review again? Thanks.

[tengqm]

All comments addressed as suggested. Many thanks for the review.

[justinmclean]

Thanks for the update.