Creating a page describing key or value

From OpenStreetMap Wiki
Jump to navigation Jump to search
Creating a page describing key or value - Other languages

This wiki has many pages documenting specific keys or values, such as Key:surface or Tag:leisure=hackerspace.

But there are many popular or useful tags that are not yet documented. It is useful to create also new pages for them. This page is intended to help with that process.

To start: feel free to create documentation for tags that are used already and there is no wiki page for them!

For example see this highly used tags without a wiki page:

The general idea of wiki pages is to tell and explain the current database situation in regard of different taggings.

Documenting tag is not a tool to redefine their meanings or to introduce new tags replacing ones that are well established. This can be done using the proposal process or after discussing it with other OSM mappers in way that gives voice to all effected (via tagging mailing list or some local forum if issue is more localized).

Who can edit

In general anyone can edit OSM Wiki and you are also welcome to do this.

But that does not mean that people are invited to redefine existing tags, for example changing description of highway=unclassified to "road of an unclear class, to be determined" would not help as it would no longer describe meaning of this tag in OSM.

Also, adding newly invented tag with 200 uses to map features is not a good idea.

New editors of the wiki sometimes mistake the wiki documentation for normative, when in fact it is empirical. The wiki documents what is used in practice; it is not - at least not primarily - a place to define what "should" be mapped. Therefore, even if you have expert knowledge about something, that still does not give you the authority to use the wiki to describe how you think a certain subject matter "should" be mapped.

On the other hand, recommendations shared by OSM community can be and are documented on Wiki and Proposal process can be used to share you recommendation with others and ask for some review.

But documenting tag on its own page? Fixing false claims? Fixing typos? That is highly welcome.

In case of doubt, consult other mappers before edits. This is especially recommended when making changes that would change described meaning and use of tags. You can ask on tagging mailing list or other contact channels - or on OSM Wiki itself, in talk pages. The more significant change, the larger forum should be used.

But other common mistake is to run a long discussion and never document anything on wiki, then several months later repeat the same discussion and again document nothing.

Proposing new tag

Main article: Proposal process

Note that if you want to create new tag it may be very useful to follow proposal process or at least consult with other mappers. Maybe such tag exists already? Maybe something can be modified to make it more useful and avoid problems while used on another continent?


Page creation

To create a new page you need to be logged in. After clicking on a red link you have the option to create a new page. Alternatively you can change the URL in your browser. A page should at least contain a description of the tag meaning and the info box. See for example initial version of Tag:construction=house page The infobox provides a quick overview and shows usage statistics automatically.

Page name

Main article: Wiki organisation#Pages naming convention

Page names in this Wiki follow certain conventions: pages describing keys start with Key: (eg. Key:highway) for tags the scheme Tag:<key>=<value> is used (eg. Tag:highway=motorway). If the page is not in English, a prefix for the language is used (eg. DE:Tag:highway=motorway for a page in German). A list of language prefixes and more details can be found here:

Main article: Wiki_Translation#Instructions for the Languages template

Infobox

Example of a minimal infobox on a page describing specific value: 

{{ValueDescription
| key           = new_key
| value         = new_value
| image         = File:example image.jpg
| description   = Brief description of the tag.
| group         = 
| onNode        = yes
| onWay         = no
| onArea        = yes
| onRelation    = no
| requires      = 
| implies       = 
| combination   = 
| seeAlso       = 
| status        = in use
| statuslink    = 
}}

Template:ValueDescription have detailed documentation about the infobox template, Template:KeyDescription is about key variant (it just have different template name and is without parameter value).

Used on these elements

By setting onNode, onWay, onArea, onRelation to yes or no you can indicate on what kind of objects a tag is used. Examples: barrier=fence does make sense on a way but not on a node.

Select a status

The table provides a quick guide on how to choose the most common status values.

For more status options and details:

Main article: Tag status
Situation Status
There has been a proposal but it was never been voted or there has never been a proposal but the tag is used in use
Like above but the tag is widely used and there is consensus on the tag de facto
There has been a successful proposal approved
A tag which was added from an external database imported

One of the best strategies for dealing with technical site of page creation is to visit existing simple page describing key/value, click edit button, copy content and paste it at a new one. For example Tag:building=church may be a good fit for a based for tag page and Key:house may be a good base for key page.

Technical Help

The OSM Wiki and Wikipedia use the same software MediaWiki. Therefore some of Wikipedia's help pages can be used but some things (like the infobox mentioned above) exist only on the OSM Wiki (and vice versa).

A short overview of the visual editor and the source editor can be found in the "Edit screen(s)" section of [1] (some other sections there only apply to Wikipedia). If you use the source editor this cheatsheet is useful.

TODO: what should be recommend as place to ask for technical help? Talk:Wiki? Tagging mailing list?

Gathering info

But often a tag is in a wide use and not documented at all. Remember that point of Wiki in such case is to document actual usage rather than describing how you want this tag to be used or guess based solely on the tag name. Following resources are useful in gathering info

  • Taginfo can help by showing usage patters
    • For popular tags there is map tab - it allows to distinguish widely used tag from one appearing in a single town
    • Chronology tab is allowing to distinguish tags added by import and mass edits (vertical jumps) from ones added by individual edits (slope without vertical jumps)
      • Chronology can also be retrieved in the OHSOME dashboard from a more featureful interface
    • Key pages also have info how many different users have last edit on objects with this tag. Note that it is not the same as "how many user accounts used this tag", but may reveal recent mass edits and imports.
    • Values and Combinations tab can help revealing common tagging patterns
  • Is it present in presets of editors? Is it tag that was discussed on issue tracker of JOSM, Vespucci, StreetComplete or iD? (TODO: link issue trackers)
  • Is it something that was discussed on tagging mailing list or somewhere else?
  • Is it clearly duplicating other tags? For example if shop=fresh_vegetables_and_fruits is used 1200 times it is worth documenting only as duplicate of shop=greengrocer
  • Overpass Turbo
    • TODO: give more info
  • Own knowledge - but remember to check how it is used elsewhere!
  • Documentation on this wiki and elsewhere
  • You can ask directly people who used tag using changeset discussion, useful especially for tags that were imported
  • If tag was imported - it should be documented on import documentation page
  • Use "What links here" on side panel (in "Tools" section). It works also on not-yet existing pages. It is possible that other pages already mention this tag and may contain some information or reveal related tags.

This strategy above is also useful for improving wiki pages, not only creating new ones.

Sometimes during gathering info you may discover vandalism, copyright violation or undisscussed import that should be reverted. Please, do this or contact people capable of handling this.

It is normal to spot invalid or highly suspicious data during such research - if you are unable to fix them remember to create notes about any spotted issues!

What is useful

  • Description of feature, even if it obvious (meaning of shop=convenience is not obvious for people with limited English)
  • Useful information about tag - it highly depends on specific tag (TODO: be more specific)
  • For key: valid values
  • Related tags, especially in cases where there is an alternative tagging or something often combined together
  • Tagging example such as this one are often useful.
  • how to map guide section
  • Infobox with filled summary
  • Filled tag status

Image

Main article: WikiProject Cleanup#Images
Main article: Wiki_Help#Include_images

Good images can be as important as the text description of a tag.

  • Image in infobox serving as a good illustration. Ideal image would be
    • Uploaded to https://commons.wikimedia.org/ or optionally this wiki (it must be uploaded to one of this sites)
    • Illustrating given tag/key
    • Not misleading
    • Well looking even if displayed as a tiny thumbnail
    • For bonus points: interesting and a good photo on its own
  • Additional images
    • If the tag covers a wide range of real world features, additional images are very useful. Good example: highway=track

Finding a good image

example of an image considered to be within scope of Wikimedia Commons: "Reasonable quality photographs of identified places are very unlikely to be considered not in scope [...] scope is very broadly defined. Reasonable quality photos of public places are generally considered to be in scope. So, please go ahead and upload those photos."[1]
One of photos taken and uploaded to Wikimedia Commons as illustration for OSM Wiki. Used on Key:turn:bus:lanes. It was taken solely for purposes of improving OSM Wiki, but is one of types of images welcome at Wikimedia Commons, and anyone else also may use it.

You can try searching on Commons, visiting relevant Wikipedia articles and using that to locate image or using categories on Commons to locate fitting image.

If you are unable to find a good image on Wikimedia Commons you can upload new one there. Or directly to OSM Wiki.

Note that uploaded image must be either on open license (author released it under license allowing such use). There are some rare exceptions such as "fair use", but none applies to images used on tag pages.

You can simply take own photo and upload it to Wikimedia Commons and make your own decision to release it under open license. With some exceptions you can almost always do this with photos you have made.

If you understand licenses you can also upload images made by other to Wikimedia Commons. They have nice guide about this. There are also some special tool for example tools for transferring eligible Flickr images.

Note that it is perfectly fine to modify image from Wikimedia Commons and upload modified (for example cropped), see Commons documentation page (you need to specify source and license correctly)

Translating pages

Main article: Wiki Translation

See also

External links

References

  1. ↑ "Realistically useful for an educational purpose". Discussion archived on Wikimedia Commons.
Retrieved from "https://wiki.openstreetmap.org/w/index.php?title=Creating_a_page_describing_key_or_value&oldid=2551499"