docs: glossary for keyboard author

[Meng-Heng]

Fix: Build a glossary page for keyboard authors (developer/language/guide?) (link to Google Sheet)

I put together a glossary page with a few new glossaries but the others are from Keyman Glossary

@mcdurdin, @darcywong00, @LornaSIL, could I ask for your input on what else to add?

---

Questions and Request:

1. Is developer/language/guide a suitable location for this? ✔️ Answered
2. Appearance preferences? ✔️ Answered

• 
• 

3. Please help add more to the content.

Thank you!

[LornaSIL]

I would like us to define "package" and then maybe start using the word "bundle" for when we put 2 or more keyboards together into one distribution.

Then, I'd like the packages folder to be renamed bundles (there are no packages folders in experimental or legacy. What do you think @mcdurdin ?

[mcdurdin]

Then, I'd like the packages folder to be renamed bundles (there are no packages folders in experimental or legacy. What do you think @mcdurdin ?

I think this needs to be a separate discussion. The term 'bundle' or 'bundling' was used in the past for bundling Keyman together with keyboard packages, so I am hesitant to overload the term now. But a change like this needs to be in a separate issue on the keyboards repo if we want to explore it.

For this PR, it'd be good to define existing terminology as clearly as possible, without changes. We can iterate on changes once we clarify how we already use terminology.

[mcdurdin]

I still need to review the terms in the list; I think there are quite a few we still need to define, and some of the definitions probably need a bit of input from me and others on the team.

[ermshiperete]

As for the appearance, I like the first option better. I think it makes it easier to see the terms if they show up as headings, plus I like it to see the terms in the index as well.

[ermshiperete]

You might want to look at my comments in the "Files Changed" tab - here in the "Conversations" tab you loose the context which makes some of them hard to understand.

[Meng-Heng]

Thanks @ermshiperete!

[mcdurdin]

I think the file should be called glossary.md

[Meng-Heng]

It is already renamed to that.

[mcdurdin]

Yes, sorry, the comment was pending on my review and could not be deleted due to the file rename! Ironic.

[mcdurdin]

We should link to the &mnemoniclayout system store documentation here too

[ermshiperete]

LGTM

[mcdurdin]

I am not sure about the advisability of including lots of content in the glossary that is also elsewhere. It's likely to get out of sync in the future as we edit. (@sgschantz you like glossaries, what do you think?)

[mcdurdin]

Tagging @sgschantz again

[sgschantz]

It can be painful to maintain two locations with overlapping content because they are eventually going to diverge.

If we look at it from the perspective of the users, then we need to ask what will make their lives easier. I think it is justified to have two glossaries if the target audience is different enough. We also don't want either audience to have to know about both glossaries and check the second if the first does not contain the term they need. It's hard to remember where one is located.

So that means that we either repeat information to make it easy for every that's using either glossary, or the glossaries link to each other. Linking between glossaries is still pretty messy, because the user is still jumping back and forth.

I guess repeating information is probably best while possibly simplifying the entry if it is for a less technical audience.

The only other option I can think of is to have a single glossary that contains everything and is not specialized for different types of users. Maybe it could still cater to multiple audiences with an indicator on some entries as to identify them as more technical.

[Meng-Heng]

Thank you for your suggestions @sgschantz.

How about we just have this to show file and folder structure, remove the short description, and with the use of a link (https://help.keyman.com/developer/current-version/reference/file-layout) to allow user to read more?

This way; I'm taking your concern into consideration, @mcdurdin; the future changes won't be too out of sync or hard to update.

Therefore, this glossary will provide just enough information for a less technical audience while also be a gateway to a more technical information.

Hopefully I have concluded it in the middle, or have I not made any progress on the concern?

[mcdurdin]

@sgschantz, this wasn't really about two glossaries, but rather the glossary copying content out of other documentation. On multiple glossaries, in terms of two different audiences, I think that will necessitate duplication. The glossaries we have for Keyman team developers will overlap with info for integrators and also with info for keyboard authors. I'm okay with that. Ideally the content for each term is tailored to the target audience, and even could be cross-linked between glossaries.

@Meng-Heng wrote:

How about we just have this to show file and folder structure, remove the short description, and with the use of a link (https://help.keyman.com/developer/current-version/reference/file-layout) to allow user to read more?

I think rather than showing the file layout here at all, just link to the file layout topic. Just have a single sentence stating that we have a standard file layout for Keyman keyboard projects.

(The file types list may be okay, perhaps take .ttf and .ico out of the list as they are not really specific to Keyman)

Therefore, this glossary will provide just enough information for a less technical audience while also be a gateway to a more technical information.

@Meng-Heng, that's perfect. A glossary should be a gateway to deeper information.

[Meng-Heng]

Thank you, I will make the changes later this afternoon.

[mcdurdin]

LGTM, one question for Shawn