Getting started with editing OpenStreetMap can be intimidating to someone who has never edited a map before. I recently spent time improving the iD editor walkthrough, a tutorial that guides new users through some basic editing tasks and teaches them the skills and confidence to improve OpenStreetMap.

Hundreds of new users make their first OpenStreetMap edits every day, and the iD walkthrough is often a user’s first introduction to editing on OpenStreetMap. It’s important to make a good first impression.

start the walkthrough

First time users are prompted to "Start the Walkthrough".

Show, don’t tell

The iD walkthrough takes place in an example town where users are free to make practice edits without affecting the real OpenStreetMap.

Previous versions of the walkthrough included some roads, rivers, and landmarks, but the data was a bit sparse. I realized that if we expect users to be better mappers, we need to first show them what a well-mapped town looks like.

The updated walkthrough includes detailed buildings, parking areas, and businesses with names and addresses. Streets are connected to sidewalks and crosswalks. Traffic signals, stop signs, fire hydrants, restrooms, and picnic areas can be found throughout the town.

before and after

Before and after - many details added.

Gentler introduction to jargon

While testing the walkthrough with people who have never used OpenStreetMap before, I realized that jargon was a real problem. There were steps where the old walkthrough would use a phrase like “add more nodes”, and some users would get frustrated because “nodes” is an unfamiliar and unfriendly word.

When you use jargon phrases without first defining them, not only does it interrupt the user’s mental focus on learning, but it also makes the user feel dumb.

The updated walkthrough attempts to introduce OpenStreetMap jargon in a gentler way. New concepts are presented in extra steps, and jargon phrases now appear in italics.

introduce jargon

Extra steps help introduce unfamiliar concepts.

Learn at your own pace

The previous walkthrough automatically pushed users through certain steps after some time had passed. This was a problem because not everyone learns or reads at the same speed. It’s important to remember that some users might not be very familiar using a computer mouse, or might not be reading the instructions in their native language.

I wanted all users to feel more comfortable with editing, so I changed the flow of the walkthrough to allow users to click “OK” to advance through the steps at their own pace.

click ok

Users control the pace in the updated walkthrough.

Each chapter now ends with a “free play” step, returning control back to the user. Goal-oriented users may want to continue to the next chapter, while hands-on learners might feel more comfortable practicing their new skills. Others might want to just explore the city or doodle. All of these learning styles are totally fine.

free play

Users now have more opportunities to explore and experiment.

Improved localization

The entire iD walkthrough can now be localized to any of iD’s 70+ supported languages, making the tutorial accessible to many more users worldwide.

This means that instructions and prompts can be written in a user’s preferred language, but also everything else in the example town – street names, businesses, and even address details.

I also upgraded the walkthrough to improve support for right-to-left languages like Arabic and Hebrew. iD is translated by a team of volunteers, so sign up on Transifex to get involved!


The entire walkthrough is localizable, even place names and addresses!

New walkthrough content

There is much more content in the walkthrough than ever before. We now teach users how to undo their work, split roads, move points, and use the new right-click edit menu, built by my colleagues Kushan and Rasagy.

right click menu

A new right click menu replaces the old radial menu.

Many walkthrough improvements were based on community feedback on the iD issue tracker, reviews of new user edits, and interactions with new mappers at mapathons and events.

I’m always listening to feedback about how to improve iD for beginner mappers. Happier users lead to more community engagement and better data in OpenStreetMap.

square corners

We now teach users how to square building corners!

Get Started

Editing OpenStreetMap is easier that you think! Sign up for OpenStreetMap, then click “Edit”, and try out the new iD walkthrough. Even if you are an experienced iD user, you can replay the walkthrough by pressing H to open the Help screen.

Follow me on Twitter for updates about the iD editor, or to let me know what you think of the new walkthrough.

And check out the iD project on GitHub to make suggestions, contribute code or translations, or to learn what we’re building next!