Detailed documentation of our vocabulary

[fwkoch]

This includes:

• project
• element
• attributes
• texture

[michiboo]

Hi I would like to contribute to this project, do you think this is good issue for beginner? If yes can you please give some guideline?

[fwkoch]

Hi @michiboo - thanks for the interest! We would love to have your contributions! Please refer to the contributing file for general information on how to contribute.

Regarding this issue as a good first issue, that depends on your perspective. This issue addresses a pretty big gap in the OMF documentation: Fundamentally, what do the words we chose for different objects mean? Language is complicated, and even if we spend hours in a room debating what most people think makes sense to call some-specific-thing, there will be others who disagree or bring different interpretations/perspectives/etc that lead to misunderstandings. The only way to get around this is to bring everyone to the same level by defining all our vocabulary. Then, when we use a word like "element" or "attribute" everyone can set aside their pre-conceived notions and refer to the documented OMF definitions.

There is definitely value to tackling this as a first issue - you would be learning for the first time what different words mean, in the context of OMF, so you would bring a fresh, relatively unbiased perspective to the definitions (if that makes sense?). It would even be hugely valuable if you opened a PR with just an early sketch of the definitions; this would provide a place for others to review, have a conversation, expand, and reach agreement.

---

If this still sounds like something you are willing to take on, great! I'd start by creating a new vocabulary.rst file in the doc content folder and referencing that from index.rst. Then just add a section for each word; they need definitions, of course, but also examples, pictures, synonyms (maybe equivalent words in different fields), etc. A few quick notes on the words listed in the top comment:

• Project - "top-level" OMF object that holds everything
• Element - 3D object (Note: "Geometry" exists in the v1 codebase but will be removed with Remove Geometries and move these attributes onto the element #37)
• Attribute - Values on an object (Note: this is currently "Data" in the v1 codebase - to be changed with Terminology: Change 'data' to 'attributes' #48)
• Texture - Image mapped to an object

Please add any other words you encounter that are at all ambiguous or seem to have their own OMF-specific definition.

---

If you don't feel like this is the sort of thing you want to tackle as your first issue, there are some other much more straightforward issues, such as #47, #41 / #54, #48 - I'll add some additional details to those as well so they are easier to pick up.

Thanks!

[michiboo]

Hi thanks for the helpful information!! I took a try at #41 and open a PR on this. hopefully I got it right!