Glossary and disambiguation

[Florian Scholz]

Hi,

the glossary gets richer and richer, that is so nice!

With more terms documented, I faced the problem of needing
disambiguation for the first time now.
http://en.wikipedia.org/wiki/Word-sense_disambiguation

So, for example we have a glossary entry about "signature" now:
https://developer.mozilla.org/en-US/docs/Glossary/Signature

This is about a digital signature in security.
However, you can also think of signatures in programming, e.g. function
signatures or in emails.

I think it is time to think about a convention how we want to handle
disambiguation in the glossary.

There are various possibilities. Let me list those which come to my mind
right now:

1) Keep the information one page and define all meanings on it in
different sections.
2) Create sub pages: Signature/Digital, Signature/Function and have
Signature as a disambig page.
3) Use different pages with brackets in the slug: Signature_(security),
Signature_(email), ...
More?

What is best for the MDN glossary?

Things to keep in mind:
* We use tooltips to include glossary definitions in other articles
* We want to be able to make use of some KumaScript automation, like we
do now.

Wikipedia guidelines: http://en.wikipedia.org/wiki/Wikipedia:Disambiguation

I have no strong opinion, but I think we need one convention here to
proceed.

Thanks
Florian

--
Florian Scholz
Technical Writer
Mozilla Developer Network

[Chris Mills]

> On 9 Feb 2015, at 21:40, Florian Scholz <fsc...@mozilla.com> wrote:
>
> Hi,
>
> the glossary gets richer and richer, that is so nice!
>
> With more terms documented, I faced the problem of needing disambiguation for the first time now.
> http://en.wikipedia.org/wiki/Word-sense_disambiguation
>
> So, for example we have a glossary entry about "signature" now:
> https://developer.mozilla.org/en-US/docs/Glossary/Signature
>
> This is about a digital signature in security.
> However, you can also think of signatures in programming, e.g. function signatures or in emails.
>
> I think it is time to think about a convention how we want to handle disambiguation in the glossary.
>
> There are various possibilities. Let me list those which come to my mind right now:
>
> 1) Keep the information one page and define all meanings on it in different sections.
> 2) Create sub pages: Signature/Digital, Signature/Function and have Signature as a disambig page.
> 3) Use different pages with brackets in the slug: Signature_(security), Signature_(email), ...
> More?

This is the way Wikipedia does it, and I think this works well, so I’d vote for this. It would be nice to take advantage of a convention that Wikipedia has already established - make the system easier to learn, etc. But does it cause any problems with our automation/scripting?

>
> What is best for the MDN glossary?
>
> Things to keep in mind:
> * We use tooltips to include glossary definitions in other articles
> * We want to be able to make use of some KumaScript automation, like we do now.
>
> Wikipedia guidelines: http://en.wikipedia.org/wiki/Wikipedia:Disambiguation
>
> I have no strong opinion, but I think we need one convention here to proceed.
>
> Thanks
> Florian
>
> --
> Florian Scholz
> Technical Writer
> Mozilla Developer Network
>

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status

[klez]

I would vote for the parentheses option. Also, having a page with no
parentheses (i.e. Signature) that works as a disambiguation page
(without needing, e.g. a Signature_(disambiguation) page that, IMHO
pollutes the URLs).

Just my 0.02
klez

Il 09/02/2015 22:40, Florian Scholz ha scritto:
> Hi,
>
> the glossary gets richer and richer, that is so nice!
>
> With more terms documented, I faced the problem of needing
> disambiguation for the first time now.
> http://en.wikipedia.org/wiki/Word-sense_disambiguation
>
> So, for example we have a glossary entry about "signature" now:
> https://developer.mozilla.org/en-US/docs/Glossary/Signature
>
> This is about a digital signature in security.
> However, you can also think of signatures in programming, e.g.
> function signatures or in emails.
>
> I think it is time to think about a convention how we want to handle
> disambiguation in the glossary.
>
> There are various possibilities. Let me list those which come to my
> mind right now:
>
> 1) Keep the information one page and define all meanings on it in
> different sections.
> 2) Create sub pages: Signature/Digital, Signature/Function and have
> Signature as a disambig page.
> 3) Use different pages with brackets in the slug:
> Signature_(security), Signature_(email), ...
> More?
>

[Florian Scholz]

I like this idea, too.

Disambig page, explaining all kinds of signatures:
Glossary/Signature

Entries with parentheses:
Glossary/Signature_(security)
Glossary/Signature_(function)
Glossary/Signature_(email)

Macros:
{{Glossary("Signature_(security)")}} should work then.
{{Glossary("Signature")}} will probably tell you that there are
different meanings in different contexts as we would write that into the
summary.

Consensus?
Anyone wants to write this down as a guideline?
Maybe here?
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary

Thanks
-Florian.

[Eric Shepherd]

I would prefer to use {{Glossary(“Signature”, “security”)}} and have the macro build the URL in this case; gives us more flexibility to change things in the future if need be.

On February 12, 2015 at 2:04:01 PM, Florian Scholz (fsc...@mozilla.com) wrote:

{{Glossary("Signature_(security)")}} should work then. 

—
Eric Shepherd
Sr. Technical Writer
Mozilla
Blog: http://www.bitstampede.com/
Twitter: @sheppy

[Sebastian Zartner]

The Glossary macro already takes several parameters and the second one is
used as display name. So your example could just be covered by something
like {{Glossary("Signature_(security)", "security signature")}} or
{{Glossary("Signature", "security signature", false, "security")}}, or by
changing the Glossary macro.

I'd say sub pages should be created and for them, i.e.
Glossary/Signature/security. In case people want to have pages like
Signature_(security), they could be (automatically?) created as redirection
pages for the sub pages. This makes it easier to keep track of
disambiguation pages and by that would make it possible to include the sub
pages in their tooltip. Furthermore the Glossary macro could stay unchanged
as in that case you would just write {{Glossary("Signature/Security")}}.

Sebastian

[Jeremie Patonnier]

Hello :)

In semantic term, I have no strong opinion between "foo_(bar)" and
"foo/bar" URLs. However, technically speaking, I'm more in favor of
"foo/bar". That way, it become very easy to build macro that take advantage
of the Kuma hierarchy to automate disambiguation pages.

We are currently in a state where it's no big deal to update the existing
macro to fit either URL schema. However, whatever the schema we choose, I
suggest that the usage for the {{glossary}} macro should be:

- {{glossary("signature/email", "signature"}}

IMO, it's way clearer (at least easier to read) than

- {{glossary("signature_(email)", "signature"}}

Of course, it's always possible to use redirect to match both URL schema
but it makes contribution harder as contributors will have to handle the
redirect which is not that trivial to handle.

Best,
Jeremie

--
Jeremie
.............................
Web : http://jeremie.patonnier.net
Twitter : @JeremiePat <http://twitter.com/JeremiePat>

[Florian Scholz]

Hi,

no strong opinion here either. "Foo/bar" sounds good to me, given the
readability and nice hierarchy. So, if we all agree, let's do this one.
I will mention it again in todays learning area meeting to see if anyone
disagrees. If not, lets document and apply it :)

Thanks everyone for sorting this out!

Florian.

Am 16.02.2015 um 15:19 schrieb Jeremie Patonnier:
> Hello :)
>
> In semantic term, I have no strong opinion between "foo_(bar)" and
> "foo/bar" URLs. However, technically speaking, I'm more in favor of
> "foo/bar". That way, it become very easy to build macro that take
> advantage of the Kuma hierarchy to automate disambiguation pages.
>
> We are currently in a state where it's no big deal to update the
> existing macro to fit either URL schema. However, whatever the schema
> we choose, I suggest that the usage for the {{glossary}} macro should be:
>

> * {{glossary("signature/email", "signature"}}

>
> IMO, it's way clearer (at least easier to read) than
>

> * {{glossary("signature_(email)", "signature"}}

[Jeremie Patonnier]

Hi!

I've updated to meta documentation to explain how to do disambiguation:

-
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary#Dealing_with_disambiguation

I also create the GlossaryDisambiguation macro to automatically handle the
disambiguation page (it's very rough but feel free to improve it if
necessary)

-
https://developer.mozilla.org/en-US/docs/Template:GlossaryDisambiguation

Best,
Jeremie

2015-02-16 15:55 GMT+01:00 Florian Scholz <fsc...@mozilla.com>:

> Hi,
>
> no strong opinion here either. "Foo/bar" sounds good to me, given the
> readability and nice hierarchy. So, if we all agree, let's do this one. I
> will mention it again in todays learning area meeting to see if anyone
> disagrees. If not, lets document and apply it :)
>
> Thanks everyone for sorting this out!
>
> Florian.
>
> Am 16.02.2015 um 15:19 schrieb Jeremie Patonnier:
>
> Hello :)
>
> In semantic term, I have no strong opinion between "foo_(bar)" and
> "foo/bar" URLs. However, technically speaking, I'm more in favor of
> "foo/bar". That way, it become very easy to build macro that take advantage
> of the Kuma hierarchy to automate disambiguation pages.
>
> We are currently in a state where it's no big deal to update the
> existing macro to fit either URL schema. However, whatever the schema we
> choose, I suggest that the usage for the {{glossary}} macro should be:
>

> - {{glossary("signature/email", "signature"}}

>
> IMO, it's way clearer (at least easier to read) than
>

> - {{glossary("signature_(email)", "signature"}}

>
> Of course, it's always possible to use redirect to match both URL schema
> but it makes contribution harder as contributors will have to handle the
> redirect which is not that trivial to handle.
>
> Best,
> Jeremie
>
>
>