How to get started contributing to a Humanitarian OpenStreetMap task

HOTQuickstart.md

##How to get started contributing to a Humanitarian OpenStreetMap Team task

###Overview

OpenStreetMap (OSM) is an open-source map of the world that anyone can edit. But like any map, it's incomplete.

The Humanitarian OpenStreetMap Team (HOT) helps organize people to improve the OSM map for crisis areas, mostly so aid workers can find their way around and make decisions about undermapped places. The data in these crisis areas is often very poor, or completely non-existent. Therefore any contribution you make at all will be a vast improvement, and could materially help people who are on the ground right now, looking at this data as you edit it, and deciding where to go and who to help.

There are many HOT tasks active at once. As of August 2014, the highest-priority tasks are Gaza and areas affected by the West African Ebola outbreak.

###Tasks and Tools

The HOT Tasking Manager has a list of current tasks. They all split a given area into a number of sub-tasks. Each of these areas needs some kind of mapping work – common tasks include tracing roads or buildings from satellite imagery, or identifying residential areas. Some tasks are easier than others; if you don't feel up to one of them, simply cancel out and try another!

All of these tasks involve editing OpenStreetMap. The two most popular tools for doing this are iD, a web-based tool created by Mapbox, and JOSM, a java app pronounced "jaws-um". Both have their quirks: iD has a very user-friendly interface which requires zero setup but doesn't allow much in the way of power usage, which can result in slower (but safer) mapping; and JOSM is notoriously user-surly but is super-fast for some situations, once you get all the kinks ironed out.

###Setting Up JOSM

As iD is fairly self-explanatory, I'll list a few tricks to get JOSM working for you. Here's a sample process to get JOSM set up to easily map buildings, as in the Gaza tasks.

1. Create an OpenStreetMap account.
2. Install or update Java.
3. Install JOSM.
4. Start JOSM and open Edit > Preferences.
5. In the "Connection Settings" pane (globe icon), enter your OSM login information.
6. In the "Plugins" pane (power plug icon), click the "Download list" button.
7. Search for "Buildings" in the plugins list, and when it is found, check the box.
8. Click the "Update Plugins" button, and when prompted, restart JOSM.
9. In the "Remote Control" pane (third from the bottom), check the "Enable remote control" box.

That should be the extent of the setup.

###Choosing a Task

1. In the HOT Tasking Manager, select a project, and read the instructions.
2. Click either the "Start Contributing" button at the bottom or the "Contribute" button/tab at the top.
3. Select a task – you may have to zoom in on the map to see individual task tiles, and you may wish to choose one inside a pink "high priority" area.
4. Click "Start Mapping" to lock the task, and proceed to the editor-picking screen.
5. Choose "JOSM" from the dropdown, using the small black arrow to the right of the editor name.
6. Click the "Edit with JOSM" button.

This will open the editor and load the satellite imagery and any existing OpenStreetMap data. You may need to manually switch to JOSM to see it.

###Editing the Map

These are the shortcuts I use:

• right-click to pan
• mousewheel to zoom
• "S" select tool
• "B" buildings tool
• "A" line-drawing tool
• control-shift to rotate a selected object
• "P" to separate a selected node from a selected line
• "J" to join a selected node to a selected line

About the buildings tool: this speeds the drawing of a right rectangle with a "buildings = yes" tag. If you select an existing right-rectangular-area with the "S" select tool, and then draw a building with the "B" buildings tool, it will auto-align the new building to the old one.

When you are finished, click the "Upload button" (fourth from the left in the toolbar).

If there are no problems:

1. Add a comment such as "Added buildings" in the space for comments.
2. For the data source field, click the "obtain from current layers" link.

If problems are detected, further action may be required. "Unnamed ways" are generally fine to ignore, but "Crossing buildings" or "Untagged ways" should be fixed. If those problems exist:

1. Cancel the upload window.
2. Check the "Validation Results" pane in the lower-right of the app, and expand the "Warnings" list entry until you find groups of ways.
3. Select the group with the "Select" button or by double-clicking the list entry.
4. Zoom to the problem area with the "3" key, and fix the problem.
5. If the problem is an untagged way, select the line, then go to the "Tags" pane in the upper-right corner of the app and click the "+ Add" button.
6. Add a tag: the key will be "highway" and the value will most likely be "residential", "service", or "track". Check neighboring roads to see what the local convention is.
7. Re-attempt the upload.

When the upload is successful, return to the tasking manager and click the "Mark the task as done" button.

It's no problem if you don't finish the task; just upload what you've done and unlock the task so others can work on it.

###Words of Encouragement

The satellite pictures are sometimes difficult to interpret, but don't worry too much about drawing the perfect line or shape – your work will be reviewed and modified by others, and improved with time. And remember, these are crisis areas, not tax records or voting districts – these maps will be read by people who may be in a hurry, in the dark, or in danger. In West Africa, even a rough line on a map is an expression of hope. In Gaza, many of the buildings to be mapped are already gone; but we mark the fact of their construction. Accuracy is nice, but it isn't the point.

If you'd like to see examples of the quality of work that passes muster, check out one of the green "validated" tasks. Don't worry, clicking the "Review the work" button doesn't commit you to anything – it just locks the task as though you were editing it. Load it like normal, and simply unlock the task again when you're done.

This can be hard work, but flow state is possible. If you have any trouble with this process, send me a note and I'll try to help troubleshoot. I welcome feedback on the instructions. (Thanks to @fishpatrol and @eldang!)

###Other resources

If you'd like a more detailed introduction to the world of OSM, there are quite a few overviews and tutorials, notably:

• MapGive's Learn To Map tutorial - http://mapgive.state.gov/learn-to-map/
• OSM's collection of video tutorials - http://wiki.openstreetmap.org/wiki/Video_tutorials
• OSM's Beginner Guide - http://learnosm.org/en/beginner/

Good luck, and thank you.

Peter (@meetar) m33tar@gmail.com

Thank for writing this. It's pretty close to the guide I've been wanting. There are really just three things I'd add:

• A couple of screenshots showing good work as examples.
• A sentence or two about the wide variety of tasks and difficulties, because if the top priority at a given moment is a task with relatively bad imagery or complex demands then there's a risk of putting a beginner off. I think it's worth encouraging them to try another task in that sort of situation.
• Links at the end to the MapGive tutorial and OSM's own one, with a clear explanation that these are for the people who get into the work and want to learn more, as opposed to being prerequisites.

If you think these would be useful, I'm happy to write them up properly and submit a pull request. I just want to see if they seem useful to you before jumping in.

Thanks! They're absolutely useful, and I made some changes in response. I may add screenshots later if I can find a moment.

Howdy! As a beginner I found this tutorial very encouraging and helpful. I especially appreciate the context you give for HOT mapping tasks and your words of encouragement. I added some pictures to the "Tasks and Tools" and "Choosing a Task" sections. I'd like to add pics to the JOSM editing part eventually too.

I just added photo links to my own fork of this Github Gist. Should they be added as a pull request instead? Also, has this HOT Quick Start guide been added to the HOT site or wiki page yet?
https://gist.github.com/jmarlena/5921524f2227a799ae1c

Hi @jmarlena -- I will absolutely integrate your images if you'd like to make a pull request. And I don't know that this guide has been mentioned anywhere but everyone is welcome to link to or repurpose it in any way.