When this issue is fixed, configure the Glossary Application to update pages on save, to avoid performance issues.
In the meantime, configure the application to not make any change, and let the doc writers use it manually by using the {{glossaryReference/}} macro.
And only link the first occurrence of a glossary term per page.
Create glossary pages as Diataxis Explanation pages, located in the place where that explanation makes sense in the doc hierarchy (i.e. NOT under the glossary app space).
Use capitals for glossary terms
Some glossary terms collected so far and that will need to be transformed into doc pages: Glossary Terms.
What do those terminologies exactly? Some glossaries include only terms, but I think it would be relevant for us to list abbreviations and acronyms.
I think it’d be interesting to be able to filter to get only one type of entry (term , abbreviation or acronym).
Examples of acronym I’m pretty sure I used in the doc: XS, HTML, CSS, ARIA, JS, WCAG, UI, UX, DB, …
Examples of abbreviations: A11y, L10n, I18n, …
+1 overall for the idea, but I think we should improve it a bit to make it way more useful.
Note that this glossary would also be a great reference for newcomers to understand the discussions held on here and the live chat
Personally I’m -1 to duplicate generic abbreviations and acronyms that are not related to XWiki. I wouldn’t want to us to do this extra work nor maintain it, and duplicate what can be found on the web in general.
Now ofc AWM is one that we should have for example (since it’s XWiki-specific)
What’s the advantage of using the Glossary application for this? Wouldn’t this duplicate regular reference documentation pages? How would this fit in the documentation hierarchy that we’ve been discussing so far? What speaks against simply linking to the reference documentation pages when we use those terms? The advantage of using links is that inserting links is easy thanks to the available shortcuts in the editor.
As far as I understand the documentation of the Glossary application, automatic linking also only works for single terms so most of the terms on the page wouldn’t work or would even link to the wrong page (like “Syntax Parser” would automatically link to “Syntax” on the first word).
See the implementation details. It lists all the advantages:
Macro to insert a glossary link
Ability to automatically create the glossary link on save later on (when the issue if fixed)
Also:
A single location where to find all glossary entries.
No, because they are the same As it’s mentioned, glossary entries are explanation pages from the doc and they’re located in the place where they should go, as normal explanation pages.
It’s tedious and is forgotten in 99% of the cases, making the doc not as usable as it should be if you land on a given page directly.
That’s not correct. It works for multiple words (when using the automatic on save approach which is the one proposed).
Ah, I hadn’t understood that part. I was a bit curious how it works, and I found in the code that apparently all glossary pages need to be terminal pages - is that correct? Also, from what I understand from the code, glossary links aren’t created inside macros, so automatic links wouldn’t work inside information boxes for example. Further, I would be surprised if glossary references worked across subwikis, and they also definitely don’t work automatically in XObject properties, so they wouldn’t be added automatically in extension descriptions.
I’m not sure if not supporting non-terminal pages for glossary definitions wouldn’t be a blocker as I don’t think reference pages in the documentation should be terminal pages.
I’m not against using the glossary application to automatically add glossary references, even though using macros for linking to glossary entries seems a bit heavy-weight compared to simple links. I’m not really in favor of using it manually as it seems like it is quite cumbersome to add the macros manually when the glossary pages aren’t in the default “Glossary” space unless I missed something.
No idea, but if it’s the case, we could improve/fix that.
To be checked if we need it and if we do then the glossary app should probably be improved.
That’s ok for now since the proposal is to have all docs on the main wiki, and thus one single Glossary.
In short the idea is to benefit from a feature that exists (Glossary) and that is not too far off from what we need, and take the opportunity to improve it. If we can’t use it, then it says a lot about that app and it means it’s probably not good-enough.
In any case this is an implementation proposal. If we find that we can’t use the app since it’s not ready-enough and it’s too much work to fix it, we can always change the implementation. I agree that the most compelling parts IMO is the auto linking.
However, even if it was manual, using a macro to indicate a glossary entry in the page is simpler to me than a link since you wouldn’t need to figure out the reference of the glossary page. You just need to pass the id which is the word or words.
I’m not sure about this, from the auto-linking code I would have guessed that you need to specify the name of the page as ID (so WebHome for non-terminal pages) and the reference of the parent space as glossary ID. But I haven’t checked the actual macro code to verify that.
Note that the Glossary id is the name of the page inside which Glossary entries are created. For example if you create a SecondGlossary.LOL terminal page as shown above, the glossary id for this entry is SecondGlossary.
So the glossary ID is the space. So when you have a page Documentation.UserGuide.Features.XWikiRESTfulAPI, according to my understanding, the glossary ID would be Documentation.UserGuide.Features.
We’re not supposed to pass glossaryid if there’s only glossary. Now I haven’t checked the implementation and indeed maybe there’s a current restriction in the implementation that different glossaries are separated simply by their location. This would indeed prevent us from locating the glossary pages where we want on xwiki.org doc, and we’ll need to fix this somehow.
