Make descriptions even more clear

[goodmami]

A persistent problem with our documentation is that it fails to clarify the thing it describes. For instance, here are some fields for "hyponym":

• short definition: "a word that is more specific than a given word"
• long definition: "A relation between two concepts where concept B is a type of concept A."
• Examples:
  • beef hyponym meat
  • pear hyponym edible fruit
  • dictionary hyponym wordbook

The short definition isn't so bad, but the long definition depends on the understanding that "A" is meant to be the hyponym, not "B". Also, the short definition says that a hyponym is a word while the long definition says it is a relation between concepts. We should clarify these to be consistent such that hyponym is the concept and hyponymy is the relation. Then the examples are terrible because it's often confused whether that short form means "beef is a hyponym of meat" (correct) or "beef has hyponym meat" (incorrect).

I propose the following template:

• short definition: "a concept that is more specific than a given concept"
• long definition: "Concept A is a hyponym of a given concept B when A is a subtype of B
• long definition (alternative): "Hyponymy is a relation between concepts where A is a hyponym of B when A is a subtype of B.
• Examples:
  • beef is a hyponym of meat
  • pear is a hyponym of edible fruit
  • dictionary is a hyponym of wordbook

I think the examples read more fluidly in the "A is a (relation) of B" form than "B has (relation) A" and it better matches the patterns in the definition.

Thoughts, anyone?

[fcbond]

I agree that this is a good template, and I am very ok with using "A is a (relation) of B".

…

On Mon, Oct 5, 2020 at 9:23 AM Michael Wayne Goodman < ***@***.***> wrote: A persistent problem with our documentation is that it fails to clarify the thing it describes. For instance, here are some fields for "hyponym": - short definition: "a word that is more specific than a given word" - long definition: "A relation between two concepts where concept B is a type of concept A." - Examples: - *beef* hyponym *meat* - *pear* hyponym *edible fruit* - *dictionary* hyponym *wordbook* The short definition isn't so bad, but the long definition depends on the understanding that "A" is meant to be the hyponym, not "B". Also, the short definition says that a hyponym is a word while the long definition says it is a relation between concepts. We should clarify these to be consistent such that *hyponym* is the concept and *hyponymy* is the relation. Then the examples are terrible because it's often confused whether that short form means "*beef* is a hyponym of *meat*" (correct) or "*beef* has hyponym *meat*" (incorrect). I propose the following template: - short definition: "a concept that is more specific than a given concept" - long definition: "Concept *A* is a hyponym of a given concept *B* when *A* is a subtype of *B* - long definition (alternative): "Hyponymy is a relation between concepts where *A* is a hyponym of *B* when *A* is a subtype of *B*. - Examples: - *beef* is a hyponym of *meat* - *pear* is a hyponym of *edible fruit* - *dictionary* is a hyponym of *wordbook* I think the examples read more fluidly in the "A is a (relation) of B" form than "B has (relation) A" and it better matches the patterns in the definition. Thoughts, anyone? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#39>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIPZRRGOEB3FW444REEVSTSJEN2FANCNFSM4SECLMRQ> .

-- Francis Bond <http://www3.ntu.edu.sg/home/fcbond/> Division of Linguistics and Multilingual Studies Nanyang Technological University

[goodmami]

Good 😃

Do you have a preference of the alternatives for the long definition? That is, whether the description maintains the focus on the concept or on the relation itself?

[fcbond]

I think that the descriptions should focus on the relation rather than the concept here.

…

On Tue, Oct 6, 2020 at 8:30 PM Michael Wayne Goodman < ***@***.***> wrote: Good 😃 Do you have a preference of the alternatives for the long definition? That is, whether the description maintains the focus on the concept or on the relation itself? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#39 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIPZRVW45F5RYU3LQJLB33SJMEXHANCNFSM4SECLMRQ> .

-- Francis Bond <http://www3.ntu.edu.sg/home/fcbond/> Division of Linguistics and Multilingual Studies Nanyang Technological University

[goodmami]

In that case I think the short definition should be adjusted to match. Perhaps, "When a concept is more specific than some given concept"

[fcbond]

That makes sense.

…

On Tue, Oct 6, 2020 at 11:34 PM Michael Wayne Goodman < ***@***.***> wrote: In that case I think the short definition should be adjusted to match. Perhaps, "When a concept is more specific than some given concept" — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#39 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIPZRTELVTHQ6UCLWQF4I3SJM2GPANCNFSM4SECLMRQ> .

-- Francis Bond <http://www3.ntu.edu.sg/home/fcbond/> Division of Linguistics and Multilingual Studies Nanyang Technological University

[goodmami]

@gconnect @yoyo-go Can you both take note of the above discussion when working on the relations documentation? In particular:

• For short and long definitions, change "word" to "concept" and rephrase them to focus on the relation.

  For short definitions, it's probably as simple as putting "When" at the beginning and adjusting for grammaticality. E.g.:

  • "a word that is more specific than a given word" -> "when a concept is more specific than some given concept"

  But some may require more work. E.g.:

  • "an occurrence of something" -> "when a concept is an instance of some given concept"

  For long definitions, try to make the direction of the relation explicit. E.g.:

  • "A relation between two concepts where concept B is a type of concept A." -> "Hyponymy is a relation between concepts where A is a hyponym of B when A is a subtype of B."

• For examples, try to use the "(A) is a (relation) of (B)" when it fits. When it doesn't (e.g., 'see also'), we could find a precise way of stating the same thing (e.g., "(A) is in a see-also relation with (B)"), or propose a more natural alternative (e.g., "(A); see also (B)").

[gconnect]

Alright. I will take note of that. Thanks for the clarification.

…

On Wed, 7 Oct 2020, 08:16 Michael Wayne Goodman, ***@***.***> wrote: @gconnect <https://github.com/gconnect> @yoyo-go <https://github.com/yoyo-go> Can you both take note of the above discussion when working on the relations documentation? In particular: - For short and long definitions, change "word" to "concept" and rephrase them to focus on the relation. For short definitions, it's probably as simple as putting "When" at the beginning and adjusting for grammaticality. E.g.: - "a word that is more specific than a given word" -> "when a concept is more specific than some given concept" But some may require more work. E.g.: - "an occurrence of something" -> "when a concept is an instance of some given concept" For long definitions, try to make the direction of the relation explicit. E.g.: - "A relation between two concepts where concept B is a type of concept A." -> "Hyponymy is a relation between concepts where A is a hyponym of B when A is a subtype of B." - For examples, try to use the "(A) is a (relation) of (B)" when it fits. When it doesn't (e.g., 'see also'), we could find a precise way of stating the same thing (e.g., "(A) is in a see-also relation with (B)"), or propose a more natural alternative (e.g., "(A); see also (B)"). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#39 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFPXA4B3SKXD3WIHGRJ6FXDSJQIULANCNFSM4SECLMRQ> .

[yoyo-go]

@gconnect @yoyo-go Can you both take note of the above discussion when working on the relations documentation? In particular:

• For short and long definitions, change "word" to "concept" and rephrase them to focus on the relation.
  For short definitions, it's probably as simple as putting "When" at the beginning and adjusting for grammaticality. E.g.:

  • "a word that is more specific than a given word" -> "when a concept is more specific than some given concept"

  But some may require more work. E.g.:

  • "an occurrence of something" -> "when a concept is an instance of some given concept"

  For long definitions, try to make the direction of the relation explicit. E.g.:

  • "A relation between two concepts where concept B is a type of concept A." -> "Hyponymy is a relation between concepts where A is a hyponym of B when A is a subtype of B."

• For examples, try to use the "(A) is a (relation) of (B)" when it fits. When it doesn't (e.g., 'see also'), we could find a precise way of stating the same thing (e.g., "(A) is in a see-also relation with (B)"), or propose a more natural alternative (e.g., "(A); see also (B)").

Thanks for that suggestion, I have revised the Domain relation groups and submitted the commit per your latest request.

[fcbond]

@gconnect when you are checking this, can you also make sure the relations with tests in EWN are linked to the correct test, and link to the actual page (see what I did with attribute).

[gconnect]

Alright. I will check what you did in Attribute and follow suit

[gconnect]

I checked Attribute relations but can't seem to find what you did to link the correct test to the actual page.
Example will be helpful here.

[fcbond]

Hi,

the short definitions are still not very harmonious.

You can easily seem the all from the new summary page (created as follows):
python build.py --lang en --object summary html > docs/summary.en.html

I think I would like to change the suggested template to something like:

• "one concept is more general than another concept"

so that it can be read as a definition

• a hypernym relation holds when "one concept is more general than another concept"

Note that umbrella terms like 'constitutive' may not follow this template and instance hypernymy is special, I have adjusted their definitions.

[fcbond]

This is what I did for attribute:
pdf/EWN_general.pdf#page=24

The '#page=24' links to the page. You can find the example in the doc_en.py file.

[gconnect]

Okay, I will check it again