Kaart: OSM Communication Best Practices

Introduction

With OpenStreetMap being an open source tool, anyone in the world can login and interact not only with the data, but with other OSM editors. With this in mind, it is important for us to prioritize proper communication and adhere to community standards. This document will guide you through the different types of communication and how to draft proper messages to each type.

Prerequisites

Before beginning a project in a country, either for the first time or the first time in a while, it is essential to research the country's guidelines and top editors to ensure that we are as informed and up to date as possible.

Skill Instruction

The OSM Community is made up of a variety of one-time-only mappers, casual mappers, passion mappers, local experts, GIS professionals, organized mapping teams, humanitarian groups, government workers and more. These communities are valuable as they are experts in local knowledge and drivers of local policy.

Communication Policies and Guidance

Finding Community Channels

Almost every OSM community has some way of communicating with other locals. This is extremely important as many of the policy discussions and best practices are determined within these channels. Use the following resources to identify communication channels in each region.

• OSM Community Index
• Contact channels

Forming Changeset Comments

Changeset are our most public presence in OSM. It is essential that we make good use of these comments to: prevent confusion and misunderstandings, increase the value of connections and edits, and preserve our image. Remember once you submit a comment, it cannot be altered.

The following are recommended guidelines for changeset comments and changeset discussions.

A good changeset comment is...
Descriptive:	Short, detailed comment that describes all changes made.
Brief:	Generally no longer than two sentences.
Professional:	Respectful to the community.
Spelled Correctly:	Free from spelling errors.
Grammatically Sound:	Uses words correctly.
Punctuation:	Uses proper punctuation.
Uses Positive/Neutral Language:	Avoid using confrontational or negative language.

Other things to keep in mind for a good comment:

• Keep your changesets small in size in both area and the number of edits.
  • Try to save between 30-50 changes.
  • Larger changesets increase the risk of getting conflicts and potentially losing a lot of work due to reverts.
• Keep your comments varied.
  • We want to avoid being repetitive except when your project scope is clearly outlined. i.e. updating geometry.
• Where are you working?
  • Include the city, province, and country you are working in.
• Add the project/project name.
  • Include relevant project information so it can be referenced by others.
  • In most cases these will be pre-populated for you.
• Make sure you use the correct hashtags in your comment.
  • When working on/collaborating with other organizations projects, see if they want their organization's name added as a hastag.
• Always make sure you add a comment before you upload.
• You can include the project name/number or a shortened version of the project link.
  • This gives editors the opportunity to look into the project and collaborate on it.
  • Note: Add the shortened link after the hashtags.

OR

Large changeset exceptions:

In rare cases there are some exceptions to the guidelines above. Some of these include:

• You've confirmed that a handful of features no longer exist and need to be deleted.
  • Verify that you are using the most up-to-date ground or aerial imagery source(unless using local knowledge).
  • Make all of the changes and upload in the same changeset. (Upload other changes first)
    • This keeps all of the changes in the same changeset and area so it's easy to review.
    • Make sure your comment explains what changes were made and why and includes the resource used to verify your changes. i.e. Removed features based on recent ground imagery...
• You need to revert a changeset due to the results of bad conflict resolution or a large mistake that was made.
  • Make all of the changes and upload in the same changes. (Upload other changes first)
    • This keeps all of the changes in the same changeset and area so it's easy to review.
    • Make sure your comment explains what changes were made and why.

Recommended Format
Comment:	Location:	Project:	#Hashtag:	Project link (where applicable):
Should always come first.	Should be part of/come at the end of the comment. May be part of the project name or included in a hashtag.	May also include the location. May be a hashtag.	Should always be at the end. Include all relevant hashtags for the project.	Add it after the hashtags. Use the shortened version of the project link.

For specific information on what your changeset comment should include see the Good changeset comments wiki.

Incorrect Comment	Reasoning	Correct Comment
#Kaart	No actual comment.	Added missing road geometry in Mexico City. #Kaart 2021
deleted buildings	Used suspect word(s). Missing location and hashtag.	Fixed duplicated building data in India. #Kaart 2023
Edited validatiion errors in Belgrade. #Kaart	Vague comment.	Resolved crossing highway errors in Belgrade. #Kaart
edited road geometry in Skopje # Kaart Ground Survey 2019	Didn't start with a capital letter. Didn't end with a period. There was a space between the # and Kaart	Edited road geometry in Skopje. #Kaart Ground Survey 2019

Reviewing your Comment:

It's good practice to review your comment before you upload. It's very easy to get caught up in the flow of making/uploading edits so remember to slow down for this step. This will help you catch any mistakes you may have made in your comment so you can fix them. Whenever you are making several consecutive edits (in an almost "methodic" manner), make sure you check that what you've edited matches the description made on the comment as accurately (and briefly) possible. Refer to the guidelines above when reviewing your comment.

Source Guideline

Adding a source is just as important as your comment. It lets users know which data source you used to make your edits whether it's satellite imagery, ground imagery, government data, etc. This is also useful in those cases that if & when there is some sort of discrepancy with the entered data, anyone else can check the other's used data source and confirm the reasoning behind the different criteria used in any given case. This is why using the most accurate, recent and verifiable source can be so determining. It's important to always double check you are entering the correct source for the project you are working on before you upload.

You can see recently used sources by clicking on the dropdown window of the upload pop up in JOSM.

Reading Changeset Comments

Leaving changeset comments is always helpful to notify other editors of what you edited in the area. However, it is just as important to be able to read comments left by other editors working around you.

How to view other comments:

When a feature is selected in JOSM, the OpenStreetMap Object Info plugin will display the information of the last version history of the object.

To view the changeset: Copy the link by clicking . Click the symbol to open the page directly in your browser. Click the button to open the changeset in OSMCha.

Below are some examples of a changeset in ID, OSMCha and JOSM using the osm-obj-info plugin.

You can also see changeset comment around the world by using the OSM Changeset Discussions tool.

Changeset comments throughout the world will vary depending on editor preference and project settings. Starting discussions on the OSM Changeset ID page is a great way to collaborate with the editor. Keep in mind that these discussions are open for anyone to view when opening that particular changeset. Be mindful that you are communicating in a friendly, professional, and curious manner.

If a conversation goes bad and an editor is not communicating in a civil and appropriate manner, we have the ability to report them to the Data Working Group(DWG) for further moderation. Do this as a last resort.

Forming a Message or Reply

When communicating with any other editor, please follow the OSM communication policy.

OSM Communication Policy:

• Assume good faith
• Respect each other
• Prioritize local knowledge
• Follow local mapping guidelines

There are two types of communication: proactive and reactive. We often use proactive communication to investigate policies and editing situations.

Alternatively, it is common to receive messages from other editors and are prompted to engage in reactive communication. This can occur productively where the editor is genuinely interested in learning or collaborating on our edits, or unproductively where the editor is being harsh in their disagreement of our edits. In all cases, it is our responsibility to de-escalate conflict and come to a constructive resolution. Don't let emotions dictate how you respond to difficult messages.

De-escalation Techniques
Be calm, be kind:	Staying calm and being polite are good ways to avoid conflict and calm down the situation. It helps you think clearly, stay open to other views, and helps you be open to learning.
Relate to their concerns:	Find the fact behind their words. Try to understand their point of view.
Interact in a human way:	Admitting mistakes when appropriate or asking their advice on how to handle a situation can remind them that we're human too.
Present your situation:	Let them know what materials and sources you used and explain why you made the decisions you did.
Ask what they would do:	Ask for reasoning behind their methods and be open to learning.
Present a resolution:	Use publicly available resources to support a recommendation.

Suggested Bookmarks

• Kaart: Introduction to OpenStreetMap(link)
• Kaart: Objects in OSM(link)
• OSM Community Index
• Contact channels
• OSM Changeset Discussions