Glossary page

[bgirardot]

I was reading Will Skora's osm wiki page and he has a small glossary on his page for new mappers. This seems like a great idea. I think learnosm should have an obvious, easy to navigate to glossary page. We use a lot of terms that a new person might benefit from having explained all in one place.

[jmarlena]

I've started compiling a glossary in a markdown file from these sources and I am looking for some others to make it more comprehensive:
https://gist.github.com/skorasaurus/4614619
http://wiki.openstreetmap.org/wiki/User:Skorasaurus

Where should this file live on the site? Should it be under the beginners section (perhaps the last post there)? Other ideas?

[bgirardot]

I am not sure where the file physically has to go or how to name it, but I would like to see a link to the glossary on the left hand navigation in the beginner's section. I think it should just be there for the whole site really, but hopefully for all the pages in the beginners section at least.

[bgirardot]

claire suggests we put the glossary doc in:
learnosm/_posts/en/coordination
to get started, which sounds good to me.

[pyrog]

I suggest to use a data format that could be easily use by layouts pages: http://jekyllrb.com/docs/datafiles/

The layout pages and/or liquid filter could add automatically a link to glossary entries from any words inside .md

[althio]

After a few discussions with @pyrog (thanks a lot!)...

Please view an actual example of an external site edited with github/jekyll:
https://www.healthcare.gov/glossary/
https://www.healthcare.gov/quick-guide/one-page-guide-to-the-marketplace/

The terms included in the glossary can get special treatment when they appear on any page:

• can be marked on each page with a typical format (dashed/dotty/broken underline).
• can be linked to the glossary entry
• can have a tooltip (pop-up on hover)

Under the hood:
source https://github.com/freecates/ramongil-jekyll/blob/master/glossary/index.html
layout https://github.com/freecates/ramongil-jekyll/blob/master/_layouts/glossary.html

In our site, we could either wish for:

• an automatic "glossarify" script. By default all terms included in the glossary receive a treatment for all occurrences on all pages
• manually "glossarifying", on demand with an added syntax.

IMO "automatic glossarify" would be nice-to-have as I feel it would be easier for content editors and translators. Maybe we will need to tune down the formatting if some pages are too crowded with links to glossary.

Last point: We need a multiple glossary/glossarify that cope with multiple languages.

[pyrog]

We need a multiple glossary/glossarify that cope with multiple languages.

👍
So there will be one glossary file for each language, for example:

_data/glossary/en.yml

- entry:       NGO
  see:         Nongovernmental organization
  source:      http://www.ab.gov.tr/

- entry:       Nongovernmental organization
  definition:  A private, self-governing, nonprofit organization dedicated to advancing an objective or objectives such as alleviating human suffering; promoting education, health care, economic development, environmental protection, human rights, and conflict resolution; and encouraging the establishment of democratic institutions and civil society. Some people use the term international nongovernmental organization (INGO) to differentiate those organizations that transcend national boundaries from local NGOs.
  source:      http://glossary.usip.org/resource/nongovernmental-organization-ngo
  used for:    private voluntary organizations, civic associations, nonprofits, charitable organizations

_data/glossary/fr.yml

- entry:       ONG
  see:         Organisation non gouvernementale
  source:      http://www.ab.gov.tr/

[jmarlena]

I like the idea of an automated glossary in multiple languages! In the meantime here is basic glossary I compiled from the OSM wiki site and Will Skora's OSM Newbie page. I put it in learnosm/_posts/en/coordination as Claire suggested with a header that directs readers to the CONTRIBUTE.md file to update it. See PR #333

[althio]

Thank you @jmarlena that is an useful first step, and first steps are always important!
We need content with glossary entries even more than automation right now.

[althio]

I merged at #338.

@jsanz It is not intended as a definitive glossary, just a first version with some bricks.
If you go straight into translation, do not hesitate to propose improvements for content or structure and contribute back to English.

[Nick-Tallguy]

Closing this now as a glossary was implemented within the beginner section. It would be nice to have improvements though so feel free to open it again with more suggestions or pull requests.