Talk:Beginners' guide

From OpenStreetMap Wiki
Jump to navigation Jump to search

Discuss Beginners' guide here:

Direct links to videos

The ShowMeDo site doesn't work for me. I don't think we can assume that the reader has a working Flash player, sufficient bandwidth, and is currently connected. Please provide direct links to the Ogg Theora file (or whatever video format). Thanks. Ciaran 11:46, 30 June 2008 (UTC)

Merge Starter Tutorial with Beginners' guide

As discussed at Talk:Beginners' guide there's too many pages knocking around which claim to offer a one-stop introduction to the OSM project. This Starter Tutorial is one of them. "Starter Tutorial" should redirect to Beginners' guide, merging any useful snippets of info here, which might be go well in that guide. ...or given that this is a very JOSM oriented tutorial, the JOSM help wiki could receive some of this content

-- Harry Wood 14:15, 2 January 2008 (UTC)

Solved — Verdy_p (talk) 23:04, 18 February 2012 (UTC)

Still many redundancies

I am currently merging all the information on how to record GPS tracks. I created for that a dedicated page, where I copied all the info from various other pages, that I replaced by links.

Now I came upon Beginners_Guide_1.1.1, that should basically get merged too (I took most of the information over already). What's your opinion about that ? Ben, you look like of of the the maintainers of the whole guide, would you agree me to do so ?

The instructions on Recording_GPS_tracks are very important, also for a beginner. For example, the fact that the "Lock on road" function shall be disabled is critical. It makes no sense to duplicate it into the beginner's guide though.

I have also noticed other major redundancies that need to be addressed :

  1. Beginners_Guide_1.1 vs. Mapping_techniques
  2. Beginners_Guide_1.1.2 vs. Yahoo!_Aerial_Imagery
  3. Beginners_Guide_1.2.1 vs. Making_GPX_Tracks
  4. ...

There aren't even links from the beginner's guide sections to the more complete pages.

While I agree it makes completely sense to take a beginner by the hand with the corresponding guide, I see 2 major problems with the current "implementation" :

  1. Wiki maintenance : much information is duplicated
  2. The beginner's guide simplifies too much. A very good example is the "Lock on road" problem. A beginner MUST read that on the dedicated page before recording tracks !

I would be glad to provide support in this direction, while keeping the beginner's guide clear and concise. Let me know what you think !

Ocroquette 18:20, 17 January 2009 (UTC)

It's important to note that a beginners guide isn't the same as a complete guide to xyz. There is a large amount of information on all the 'vs' pages which you've linked to. I think all this information is valuable, but not the first things people need to know. A huge page of text tends to see a lot of people off. It is better to inform them of the key points and at least have them reading it, than having them give up or go ahead with no reading at all. All further reading should be linked to I think.
The 'Recording_GPS_tracks' page should be linked to from the GPS page on the beginners guide for further reading I think also. But.. your example of the "lock on road" function being disabled is critical, I defiantly agree on that.
Duplicated data isn't that bigger issue I think, so long as the reason for duplication is 1 page being a simplified (starters) form of another, rather than the 2 (or more) pages just being slight variations of exactly the same thing.
I don't agree that the beginner's guide simplifies too much, but again I agree to the 'lock on road' problem which is the example for that point. Personally I didn't deliberately exclude this from any page at any point, but I don't know if others have consciously avoided adding it..?
"would you agree me to do so ?" I don't need to, it's not my page, although having a discussion is productive. Ben 23:04, 17 January 2009 (UTC)
OK, I have added links to the main pages that I know of. Thanks for the "Lock on road" addition. I guess it's ok this way. -- Ocroquette 15:00, 24 January 2009 (UTC)

Wiki organisation

This is following on from the above points about redundancies, but also consolidating / updating an older discussion.

We have too many pages aiming to provide an introduction to the project. Some examples which look like they are stale and unloved anyway:

"Portal:Users" is quite stale and unloved, and furthermore is named badly, because the content is giving an introduction to the project (not a portal). As an introduction, it is an unnecessary duplication of this Beginners' guide ...and yet it has been translated into five different languages, so that's awkward!

Now initially when this "Beginners' guide" was created, we already had Help:Contents linking to About, Browsing and Editing, also pages like the Map Making Overview (as it is now called). These pages, and many others, provide mostly help information of a not-too-technical-aimed-at-newbies form. So my initial thought was that the "Beginners' guide" was an unnecessary addition to the mess, creating lots of duplication (as User:Ocroquette is pointing out again above)

...but I've come round to Ben's way of thinking. It could be useful for new users to have a limited self-contained set of pages to read through, guiding them through some aspects of the project at an introductory level. That's in addition to the various other help wiki pages which adopt a more free-form wiki interlinked approach. I think there's more work we need to do on the Beginners' guide pages to achieve these goals, but as a justification for its existence, that makes some sense.

I know that many people feel that the Beginners' guide is one of the worst areas of the wiki, or the area most in need of clean-up. I've heard suggestions we "slash and burn" the whole thing. So I think we need to be clear what the justification is, and what the goal of these pages is, and maybe seek to differentiate with other wiki pages.

-- Harry Wood 01:53, 16 February 2009 (UTC)

Somebody recently added a link on this page, to a new page "How it works". This is yet another I'm going to describe the project my way wiki mess. I'll be removing that link from here very shortly.
But it did prompt me to put forward a new plan for dealing with this kind of thing. And I think it also points the way to a fresh approach to creating distilled Beginners' guide type documents without too much wiki mess. See Talk:How it works
-- Harry Wood
I've removed a link to User:Detectist/OSM Mapping (Using Potlatch) for Dummies, for essentially the same reasons. This seems like a better attempt at an intro, but it's still messy to link it from here. -- Harry Wood 04:24, 15 September 2011 (BST)

Improvements to the Beginners' guide

The Beginners' guide has been flagged as one of the key WikiProject Cleanup issues right now (a key area where the wiki is failing to deliver important information effectively to new users). I'm going to paste in a couple of comments I've found from elsewhere (hope the authors don't mind) -- Harry Wood 10:40, 16 February 2009 (UTC)

"it's a mostly unhelpful link farm detailing a particular mapping method in infinitely too many pages" -- User:Randomjunk 09:46, 23 January 2009 ([1])
I think it just needs to be four single pages:
1. what OSM is and how it works (including brief explanation of copyright and GPSs);
2. how and when to use Potlatch;
3. how and when to use JOSM;
4. an introduction to the OSM community, and ideas for where to go next.
All the core stuff, but nothing more, should be on these pages. Trouble-shooting stuff (e.g. how to download tracks from your GPS, which GPS to buy, etc.) should be on separate pages - ideally those which are already on the wiki.
We don't need a comprehensive manual, just a getting-started guide. Something like is way too much detail (I mean, does a newbie really need to know how Osmarender works?), and I think we can be fairly light on the "why do it", too - if you've gone to the Beginners' guide, you already want to do it.
-- User:Richard Tue Jan 06 23:28:27 (comment to me)

Now it should be noted that the above comments are taken out of context. I'm sure people appreciate the efforts gone in to the Beginners Guide so far, but nonetheless when people are prompted to whinge about problems on the wiki, Beginners' guide is near the top of the list. I'm sure I could find other examples on the mailing list.

So how can we improve it? I'd be inclined to agree with Richard that we should aim to limit the guide to just a handful of separate pages. I created the content template on the right hand side. This is useful for newbies reading the guide, but I also found it necessary just as a way of getting a grip on just how many pages the guide consists of, and how it is being structured (and I'm still not 100% sure I found all the pages!) Perhaps we should limit ourselves to just five or six pages. I notice the Germans (DE:Beginners' guide) have a set of six tabs, which seems to work well, and I was thinking my Template:Beginners Guide Header could be converted to show tabs at the top.

I also wonder whether the "5 steps" identified in the image, are the best breakdown of chapters to have in a guide. I suppose that's something people will always have their own personal take on. There's several different ways to explain the OSM project (different order to cover the topics) I'm thinking the distinction between "3 Edit maps" and "4 Edit data" is unclear, and also steps 1 and 2 are very GPS focussed. Pondering alternatives

-- Harry Wood 10:40, 16 February 2009 (UTC)

Proposal by User:Kempelen

Reading this whole page and seeing how old the comments are, and how outdated some parts of the documentation was (I've updated some already), and after talking to the original author, I propose:

  • Keep it practical and very simple
  • Remove notes that are not related to drawing map
  • Be a complete list of steps that results in something that the user can really upload
    • Add a facility drawing section next to "First basic road", we don't know whether a user starts with road or shop
  • Make sure all pages link to more info about the subject, but avoid links to advanced pages and avoid lists of links
  • Keep order of "collect-edit-upload" (despite proposal below)
  • Add a tagging introduction after "General tips" (a more practical one than current "Adding tags" page, which duplicates object types (found on "1.3 Edit maps") and adds a very theoretical classification of tags)
    • Thus Delete Adding tags
    • Thus Delete Edit data
  • Write editor specific "Add tags" pages
  • Integrate "Upload changes" into the editor specific sections
  • Expand Potlatch section to be a guide (match JOSM) instead list of tips
  • Delete "Render maps" info - it was written when the site didn't have a map yet(!)
  • Keep "Use map" parts, but stick to options available on the OSM site ("wait and see the data you added", "search for your added data" .)
  • Delete Merkaator section (It's no info in the current form), we can mention on a page that more editors are available and link to them

If other editors agree, I'll do these changes. Opinions? Kempelen 22:52, 15 May 2011 (BST)

Hi. Thanks for taking the time to look at this. It needs somebody to take a step back, think about structure and focus, and then figure out a way of transitioning to something better. I agree with lots of what you're proposing.
You say "Remove notes that are not related to drawing map" so make it more of a beginner editing guide. Tricky thing here is that we have some beginner editing guides for specific editors already. Potlatch 2/Primer and the older Potlatch 1/Primer are one-page guides to Potlatch, although actually they're more like cheat-sheets than guides. JOSM/Guide is a a more wordy description, but still beginner oriented, split across three pages. Both of these avoid describing some of the more generic map making principles, and things like tags, so there is a need for a Beginners' guide in addition to them, but we should avoid too much duplication. Perhaps we should try to find a way of describing map editing without mentioning specific UI elements and keyboard presses, but rather just refer (very prominently) to those other guides. It's the duplication which results in sections of this guide not being maintained. Describing editing without describing a specific editor could be challenging, but I don't think it's impossible. There's lots of concepts such as ways, nodes, tags, and using GPS and imagery, which we can introduce equally for potlatch, JOSM, and Merkaartor. To be clear, I'm suggesting we get rid of separate pages for JOSM and Potlatch from here.
'"avoid links to advanced pages and avoid lists of links", would be good. I'm thinking we should go for a more distinct look and feel for the Beginners' guide (box around it or something) and then try to link to other wiki pages only within special side-boxes (a bit like the way wikimedia projects cross-link e.g. wikibooks cookbook:beer has a very separate looking box linking to wikipedia 'beer' article) This gives a clear visual cue that the link is taking you out of the Beginners' guide and onto the rest of the wiki. In doing so, we'll leave behind fewer links in the main body of text, and these would be "internal" links between pages of the Beginners' guide. It becomes more self-contained and less heavily meshed with the rest of the wiki.
-- Harry Wood 12:28, 16 May 2011 (BST)
Hi Harry, thanks for reply. The mentioned guides are "cheat sheets", that include very good additional information once you tried and succeeded working with OSM editing. I think that initial success is missing and leading users to leave too early. Users are sent to Map_Features and such huge pages too early. (From Potlatch2 Primer too) We could allow beginners to live with a simple residential road and then classify further later, after the initial success inspire them to continue.
My idea is to get users' hands dirty - and feel satisfied with it. Giving users theoretical information of what are nodes, ways, how to edit a way in general, how to tag it, but give no chance to try is not good. What you recommend would require users to read a LOT MORE before they can actually succeed to draw anything. I think the Beginners' guide currently allows to do a very basic editing and publishing, and this could be pushed further.
I try to list current sections to try to help planning structural changes
  • 1.1 Collect data - Very good already - helps users to identify in which area they could contribute
  • 1.1.1 GPS - Good, but since the "Upload data" applies to this data source only, that must be integrated into this page. Also explain what are the uses of camera, dictaphone because not all users need this.
  • 1.1.2 Yahoo,etc: good - needs an intro of how this mapping works in general
  • 1.2 - Upload data - Intro integrates to 1.1.1, rest is not useful
  • 1.2.1 - Save your files to GPX - Shorter version goes to 1.1.1
  • 1.2.2 - Upload data - Goes to 1.1.1 - hopefully it can be shortened
  • 1.3 - Edit maps - good (section links are not needed)
  • 1.3.1 - General tips - good
  • 1.3.X - new - Adding details by tagging
  • 1.3.2 - Potlatch - convert to followable guide like JOSM (see below)
  • 1.3.3 - JOSM - add 1 sentence intro and installation steps (just a download link)
  • - Download into JOSM - good
  • - First basic road - Make it more step-by-step that can be followed directly, include both Yahoo and GPS example image of how the road is drawn over them.
  • - new: Draw a shop - Just to make another example (we should check what features most people draw. for example if much more people adds Turn Restrictions than Shops, that should be the example)
  • - Upload
  • 1.4 - Edit data - delete - tagging intro went to 1.3.X above
  • 1.4.1 - Adding tags - very bad, delete, I am not sure we can save anything from this. That would go to 1.3.X above
  • 1.4.2 - Uploading changes - goes to editor specific section
  • 1.5. - Render maps (becomes how to view your drawing on the live map, how much to wait, why your Whatever Shop isn't rendered and how to still view its data or search it.
  • 1.5.1 - Delete


  • Collect data
    • GPS
    • Yahoo,Bing..
  • Editing maps
    • General drawing tips
    • Adding details by tagging
  • Editor: Potlatch
    • ....x
  • Editor: JOSM
    • Download into JOSM
    • First basic road
    • Draw a shop
    • Upload
  • View results

However still focuses on "practical introduction to editing OSM", so you may not agree. :-) I find it most important that users can "draw their neighbor" without going to Map_Features and such pages on the first day. A few days later they will go there anyway, but that stage they feel the fun of editing, so they will accept it. :-) If that neighbor won't be perfect, users will learn and repair later. Kempelen 22:16, 18 May 2011 (BST)

Integration of openstreetbugs

hi guys. just got this link from the mailing list. i think it should be integrated into the newbie quicksteps. but i dont know how to do it best ... proposals anyone? - description:

... since there was no reaction i just tried

User:Blubbi 12:03, 17 June 2008

How to display Points of Interest from KML

I have a KMl file, at: I can paste that URL into G**gle M*ps, and this: is retuned. Can I do anything like that with my KML file, and OSM? Easily? A search on this wiki for KML was not enlightening. Pigsonthewing 16:17, 26 June 2009 (UTC)

The KML wiki page originally had a dubious redirect which I guess was screwing up your search. See KML now -- Harry Wood 16:32, 26 June 2009 (UTC)
Thank you, but the examples via there seem to require scripting. I simply want to drop the URL of a KML file into a box and then see the KML PoIs on a map, in my browser. Pigsonthewing 19:20, 26 June 2009 (UTC)
OK I've just knocked up a quick script especially for you: Bit basic though. I've not added the other features you might expect of a map display website (zoom bar, 'permalink' etc) There's probably some better OSM map displaying websites supporting KML overlays, but I'm not aware of them. -- Harry Wood 18:56, 27 June 2009 (UTC)
That's very kind, thank you, and works well. But my point was that people can do this with GM, including zooming and the like, and so OSM needs to provide the same sort of functionality, if it wishes to gain market share. I'd far rather use OSM for this, both to support it and its open-source ethos; and to do so by raising awareness of OSM among my site's visitors, but in the meantime, I'll have to remain with GM. That's not a criticism, though, and I'm very mindful that OSM is a volunteer effort - I just think it's something worth talking about. Pigsonthewing 09:28, 28 June 2009 (UTC)
So you're suggesting adding features to the Front Page Design. That discussion is ongoing (see that page and join in)
This discussion is in the wrong place. Think I'll move it to KML talk page.
-- Harry Wood 16:33, 5 October 2010 (BST)

Moving 1.2.2 under 1.3.1?

I'm thinking about moving the section 1.2.3 Downloading into JOSM to (and shifting the other sections there down) since that section is only relevant for JOSM users. Good idea/bad idea? Thanks, AxelBoldt 05:22, 20 September 2009 (UTC)

Seems to be moved to Beginners Guide now.
Incidentally it's a problem with this wiki page naming scheme, that pages need to be moved around a lot to do a renumbering. reminds me of programming in BBC BASIC. Ultimately though, there should probably be fewer pages anyway (commented above)
-- Harry Wood 16:36, 5 October 2010 (BST)

Suggest a bit overhaul here

Hi guys, I'm brand new, and this Beginner's guide (and most of this wiki) confused the hell out of me. It assumes that the person arriving here has already decided they're going to get a GPS, drive around the city, collect data, and upload it. Probably unrealistic for a newbie. In fact, the sequence of operations (collect data, upload, edit, use) is probably almost exactly backwards. Newbies need this sequence of information:

  1. How to view OSM data online. (and maybe download it)
  2. How to edit OSM data online (using Potlatch - for god's sake, stop scaring us poor newbies with all the unix techo talk. you have a GOOD online editor, why hide it??)
  3. How to edit OSM data offline. (maybe)
  4. How to upload a GPS trace, and use that to edit with.
  5. How to go out and get new GPS traces. (maybe)

There's a lot you can do these days without getting out the GPS, especially with all the Yahoo and Nearmap imagery. Suggest you focus on helping newbies get their feet wet with Potlatch before scaring them away. Oh, and don't tell them it's called Potlatch - just tell 'em it's the online editor.

Stevage 18:05, 25 November 2009 (UTC)

I agree that sequence of chapters is maybe not the best, although it's actually not obvious what the best order is to explain concepts in. But yes the balance of opinion in the community has shifted over the years, towards being more accepting of "armchair mapping" (mapping without surveying first) and paper based mapping without GPS. The guide could be re-ordered to reflect that, and to introduce these easier techniques first. Another idea I was pondering on with User:Gravitystorm, was some sort of decision tree to figure out what kind of mapping a new user is likely to be interested in. e.g. users in the U.S. will have a very different first experience due to the presence of TIGER data.
- Harry Wood 15:42, 1 December 2009 (UTC)
Personally I think the first page should be be a set of stub articles describing how to do very common very simple things to improve the OSM data each linking to an short article with pictures that shows how it is done. For example 'To correct (or add) a road name', 'to add a street or stream','To add a point of interest', 'To align some mapping better to Bing imagery, 'To use Walking Papers to go and do a manual survey', 'To add detail to the Waterways', 'To add detail to a railway station'. The aim of the first page will be to allow people to ideally immediately identify the thing that they want to do first and then take them carefully through the process. The articles for each activity will need to either stand alone, or alternatively the user will be expected to do each activity in turn learning something new each time and never being assumed to know something they have not been told. This is classic tutorial writing stuff - I will take a look at this a try some ideas out in a non destructive way.PeterIto 19:46, 23 December 2011 (UTC)

Contributors' guide?

See also Contributors' guide

I believe that the scope of this guide is to describe how people can contribute data to OSM, rather than to describe how people can use OSM data within 3rd party products, applications or services? As such I suggest that we consider renaming it as the 'Contributors' guide'. I am going to have a concerted go at this subject now and see what I can make of it. PeterIto 19:37, 23 December 2011 (UTC)

OK, I have started working on this and based on the discussions above and in the WikiProject Cleanup article I am going to be pretty ruthless with the current content. In particular I am going to leave JOSM, GPS and relations until a later guide. What the Beginners' guide will be very gently, simple, carefully and show people how to add nodes and ways and tag them to do a bunch of basic things and that it pretty much all it will do. First off, I am going to 'move' the current article to names that reflect their purpose without the numbering which get in the way of reorganising the content and dropping pages. PeterIto 10:26, 24 December 2011 (UTC)

This help guide seems to have lost everything that made it what it was. It now has relatively sizey wods of text. It was aimed to be short concise pointers with attached diagrams and pictures. Half of the information is really not needed initially. This is teaching about the gears, before learning to ride a bike. "keep it simple stupid". Can we aim for vast simplification and reversion. We need to remember that not everyone thinks and learns alike; these large blocks of text are highly off putting to many, deterring them, ironically, from such a visual project. I disagree with the point of not seeing GPS input as the standard work flow, made by some. There are other sources, but not equal to on-the-ground research methods. I strongly agree with PeterIto's points before also. Ben 07:00, 20 January 2012 (UTC)
Thank you for the feedback and encouragement. I am developing a much more straightforward Contributors' guide separately from this one with a view to replacing this guide with it when it is complete. Can I suggest we discuss what to include in this new guide on Talk:Contributors' guide? At a later date we when it is complete we will raise a proposal here to replace this guide when the new one is ready. PeterIto 08:30, 20 January 2012 (UTC)

Hi Peter. I don't like the idea of making a new "contributors guide" instead updating the current "beginners guide". One year ago I tried to rework the beginners guide, please see Talk:Beginners'_guide#Proposal_by_User:Kempelen above. Maybe you and me could work together to make "Beginners guide" a good guide where new editor can learn the basics. And we would merge "Contributors guide" idea. It would be cool if new users just need to learn one document to be able to make their first basic changes to OSM map.

If you want we can try to develop it in a "sandbox" area of the Wiki, to disturb the online links as little as possible, and then overwrite the current "Beginngers guide", however this gives less publicty and options for other feedback, so after a basic planning, the editing should be done on the online Guide probably. We need to rename the unmaintainable section-numbered pages, but we can make redirects to the related sections, so no problem.

-- Kempelen 12:05, 20 April 2012 (BST)

Thanks Kempelen. What I would say is that one needs to be very clear about what a guide is aiming to achieve before working on it. What is the scope of the beginners guide? Is it a guide for newbie contributors to OSM, or for people wishing to use osm data, or even to contribute code? Is it covering Potlatch only, or JOSM or both? What about GPS trails etc. It seemed to me that the beginners' guide has tried to cover everything and was probably created at a time that the only meaningful way to contribute was using GPS. With the contributors guide I was aiming to narrow down the options. I choose to limit the guide to someone using Potlatch, aerial photography and local knowledge for the first tutorial; nothing about JOSM and nothing about GPS to keep it simple. Unfortunately I became clear that the job needed more time that I had, and also that I was not getting a lot of encouragement from others. As such it has fallen by the wayside. I am not sure that I will be able to contribute much time to this at present but I would be interested in discussing the scope of what you have in mind. PeterIto 14:10, 20 April 2012 (BST)
Hi Peter! GPS is fun. JOSM is a very good editor, also for beginners. What you describe is near to the Potlatch 2/Primer article. A beginner, coming to OSM will want to have an overview of options, and this guide should give it to them.
- Can I upload a way from my phone-GPS?
- Can I update my local area walking without GPS?
- Can I just sit in front of computer and do mapping?
All these are possible, and current Guide mentions them. This gives a place for everyone in the project. More (should be added):
- How do I fix a wrong street name or position or direction of oneway?
- How do I add my favorite restaurant? etc
I agree with Ben, that huge walls of words are totally bad for Beginner's Guide. I've changed several pages of the Hungarian translation to use images, bulleted lists, easy step-by-step guides and no alternative ways or options.
People will not come here to trace towns or buildings from satellite day and night. Your assumption (in contributor's guide) that someone will want to search for a place to map is wrong. Someone will know where and what they want to change or add, but need to learn how. Please read my Talk:Beginners'_guide#Proposal_by_User:Kempelen

Translations of the “Beginners Guide”

I’m coming from the german page of WikiProject Cleanup. The main object of this page is to have all articles directly necessary for mapping translated to german. The “DE:Beginners_Guide_1.0“ is one of the articles in the TOP10-list. Changing language to english version did not allow me to see the english version (Beginners Guide 1.0) but I was redirected to “Join the community”.

After a short discussion I translated this “new” page except the table of content (being a template). After looking around in the Beginners Guide in the different languages I wonder

1. why all chapters of the Beginners Guide are named “Beginners Guide x.y” except the first chapter after the introduction page: the page is not named “Beginners Guide 1.0” as expected but “Join the Community”. If different pages with similar information have been consolidated I would have redirected the latter to “Beginners guide 1.0”.

2. which structure is going to be the future one: “normal” pages using a template as table of contents on the upper right side (like in English, Cesky ..) or a page with several tabs for the chapters in the upper line (like in German, Slovenščina, ...) (see also Improvements to the Beginners guide).

I could add the tabs or create and add the template-tables in languages which have nothing of both. - what of the both should I do?
What is with the pages like english or german: should there be different (more or less optical) structures existing in different language versions or should they be unified? Who decides something like that?

3. why several languages do not have the chapter “join the community” in their table of contents (deutsch, Español, Română Slovenščina, Türkçe) event though they have either a page “Beginners Guide 1.0” and/or “Join the Community”

My proposal: I could amend this chapter in those 5 languages if there are no contradictions.

4. why in some languages there is still an active page “Beginners Guide 1.0” (Česky, Deutsch, Français, Magyar, Русский, Українська), in some there is a passive one being redirected to a new “Join the Community”-page(English, Español) and one even has an active page “Beginners Guide 1.0” but with the contents of the “Join the Community”-page (ไทย). In some languages we have new “Join the Community”-pages (Deutsch • English • Español (no table of contents) • Română • Slovenščina • Svenska • Türkçe). The Previous/next-links are not always working correctly within the language but partly going to the english versions.

What should be done in order to get a straightforward line throughout all language versions?

--Rennhenn 22:16, 8 August 2012 (BST)

Move some older discussion topics to an archive subpage

Hello all, would you mind if I create an archive subpage to this discussion page and move some of the older topics to this subpage - maybe by referencing the topics from the main discussion page together with the date of the newest update to the topic?

My reason behind: I currently try to get an overview about the cleanup discussion in some areas of the wiki, but it's really hard to read through all discussions and verify which discussions are obsolete and which ones are still pending. --MichaelS 21:21, 23 December 2012 (UTC)

Cleanup Request

Hi, luckily a few german users start to redesign the beginners guide from scratch. Even if this isn't the very best solution (as it currently doens't involve international part of the community), we should give them time, to show the first result that we can work on together. Plz see german talk page and feel to contact me for any questions --!i! This user is member of the wiki team of OSM 14:33, 26 January 2013 (UTC)

We could also offer a external alternative beginner's guide - newly designed by the MapBox company: Description of it. I did just quickly skim it, I already noticed that they nearly only introduce in JOSM (just quickly in Potlatch2). Anyway - if iD gets the new default beginner editor (and if it proves good) that tutorial needs to be updated. ;-) --Aseerel4c26 (talk) 20:09, 31 March 2013 (UTC)

Refer to iD

The iD editor should be referenced in the Beginners Guide sidebar --Wyken Seagrave

Well, yes, see directly above. --Aseerel4c26 (talk) 02:35, 1 June 2013 (UTC)
Abolutely not for now. Even if iD is intended to be used by beginners, it is still far from being ready for use by anyone. Notably because it still lacks very importnant features that even beginners should be exposed to, even if they don't enter this kind of data : relations. Almost all users of iD are breaking lots of things in maps, that users of other editors now constantly have to repair or restore; beginners using iD don't see why some elements are present on the map, because there's absolutely no useful tag or indicator that these elements are needed and used, and they delete, or move them.
Since the introcution of iD, we now have much more work repairing things that are broken by users of iD. Clearly iD is still a beta, and definitely not at stage 1.0.
iD for now is just usable for very local edits.
And if iD cannot work with relations, it should completely hide all objets that are members of any relation, or it should clearly say to users that these objets are members of some relations (preferably listing at least with their name or note), even if users can't edit the relation memberships within iD.
This will save us hours repairing things (and lots of megabytes to download things, consult the histories, and restore things that were incorrectly deleted.
Thanks. — Verdy_p (talk) 09:55, 6 June 2013 (UTC)
The developers of iD are looking into adding relations features (and of course struggling to find a way of making them beginner friendly) It seems like you're saying this is a priority, and that *all* relations should be visible in the editor somehow (not just preset types) I'll add a comment there on your behalf -- Harry Wood (talk) 11:52, 6 June 2013 (UTC)
Hi Verdy_p, I'm an iD developer. As Harry suggests, iD 1.1 will have improved support for relations editing. Read more about it here: Sorry to hear that some users have been damaging relations when they edit with iD. To make sure we are on the right track with changes to iD that will make this less likely, can you provide some examples of changesets where this has happened? It will help us better understand what types of situations we should design for. Thanks, Jfire (talk) 15:43, 6 June 2013 (UTC)

Privacy section

Tirkon added the following text:

Before you consider contributing to the OSM map, be aware that every edit you do will be assigned to your username. This information will be published together with the geodata under the free OSM-licence. That means everybody - even outside OSM - will be able to analyse when and where you did which contributions to OSM. You will find examples of such analysis here. Consider in particular your personal environment is possibly able to identify you even if you do not use your real name at OSM. For more information read the Privacy Policy.

This appears to have stemmed from a concern of a few users on the German-language mailing list. This concern has not been expressed by the OSM community in other areas and, in particular, by the English-speaking community at whom this English-language page is clearly aimed.

To add this as the first paragraph (after the standfirst) of the 'Beginners' Guide', which for many people is their introduction to OpenStreetMap, would suggest that this is the most important aspect of the project for the majority of users. Clearly, for most people, it isn't. All this lengthy paragraph does is add yet further complications to what is already a highly confusing document.

I would suggest that the very small number of users who are concerned about this aspect of their privacy will know to read the Privacy policy. If the latter doesn't adequately cover this topic, that is of course another issue but one that should be addressed in that document, not here.

(On the wider point, separate to this page; OSM is about community and the best edits are done by those who are prepared to be part of that community. Absenting your online persona from this community shows bad faith, and I am not convinced we want to encourage such people to take part in OSM. It's notable that the people who have caused most damage to the OSM community over the years tend to be those who have gone to great lengths to conceal their identity - "NE2", "John Smith" etc.)

--Richard (talk) 12:26, 28 July 2013 (UTC)

2014 Updates

There is duplication between the Beginners' guide and pages linked to from Template:HelpMenu. I would like to start by doing the following:

  • Rename page titles within the Beginners' guide - e.g. "Collect Data" is a better page name than "Beginners Guide 1.1" as it is more discoverable via google or wiki search, and would make the beginners' guide much easier to reorganise.
  • Merge content from Template:HelpMenu pages into the beginner's guide and delete the Template:HelpMenu - this will simplify the wiki.

Please let me know your thoughts. --RobJN (talk) 13:50, 15 February 2014 (UTC)

Renaming page names of beginners guide sounds good to me. But merging the help menu pages with the beginners guide.. To me the beginners guide covers only "contribute data" and not "about OSM" and "browsing OSM world map". I would prefer to keep the beginners guide more focused and not to add these chapters. Instead, one could create a "tour", containing several pages, showing around the OSM world and highlighting main aspects. This tour could also be an entry point for newbies in the "about" group in my proposal, like the beginners guide is an entry point in the "contribute" group. --Cantho (talk) 11:15, 17 February 2014 (UTC)
What about numbers and content-based titles? Btw: all should be subpages of beginners' guide.
I agree with Cantho that the beginners' guide should be as focussed as possible. Deeper info is provided by links.
Cantho mentions "tour" - just a crazy idea: how about deleting the guide pages completely and make it only a tour of several other pages (which are already in a better maintenance status and usually already include a introduction)? This would avoid duplication. Those pages could be linked by such a navigation bar. Well, and a main problem will be: which editor to recommend and use in potential examples (see discussion about iD above). Or just link Comparison of editors? Just wanted to share my first thoughts. Will get back to it later (today). There are several sections here on the talk page which look as I / we should read them. --Aseerel4c26 (talk) 12:09, 17 February 2014 (UTC)
I think a little bit of duplication is not necessarily a problem, if we're clear about the aim. The aim with special set of wiki pages for beginners, would be to keep it short and sweet somehow. The aim would also be for the beginners guide to be a self-contained document for a beginner. That's actually a difficult aim for a wiki because people love to chip in with more details all the time, but for a beginners' guide.... less is more. Imagine if there was a rule maximum five pages each of max 500 words. Anyway that's an age old discussion
Renaming the pages could be good. I can imagine that being a useful step if Beginners Guide 1.1 was renamed "Beginners Guide - Collecting Data" or perhaps " "Beginners Guide/Collecting Data". With that name, the page would continue to be part of the self-contained document and a little bit separate from the rest of the wiki, but as you say, reorganising becomes more do-able.
Maybe you were proposing to rename Beginners Guide 1.1 as "Collecting data" with no prefix. That would sort of set it free to mingle and mix and mesh with the rest of the wiki much more. I think that would create a lot of mess though. Lots of duplication with other pages to resolve, and in the end we wouldn't have a beginners guide any more, partly because it would end up being meshed with the rest of the wiki so wouldn't feel like a self contained guide, but more importantly it would cease to be written specifically for beginners. It would become like any other wiki page: Some beginner-friendly intro if you're lucky, but also lots of detail.
Not sure what kind of renaming you're proposing exactly.
-- Harry Wood (talk) 16:26, 17 February 2014 (UTC)
I'm quite happy with some duplication, where appropriate. We need to keep the beginners' guide very focused and link to more detailed documents which are likely to start by covering the same basic content. What I'm not a fan of is pages that are almost identical - for example see Beginners Guide 1.6 and Help:Contents.
I was suggesting renaming without prefix. To me the Template:Beginners Guide Header works to keep the pages organised and as a "set" and titles that include "Beginners' Guide" just make it harder to add/remove pages to the set as OSM continues to evolve.
I also have no issue with pages starting to "mingle and mix and mesh with the rest of the wiki". Taking the example of the two help pages; I see no problem with users who search for "help" finding a page in the Beginners' Guide. In fact dropping them in to the Beginners' Guide is probably a good thing!!
Regarding Cantho's point about the Beginners' Guide being a "Contributors Guide"... Not sure on this one. Gut instinct is that OpenStreetMap is about more than just contributing data (e.g. Use of data - complex or very basic, Developing the code, building communities, etc..). Let me take some time to actually see what other basic pages there are in the wiki and I may have a better idea of what will work.
--RobJN (talk) 22:33, 17 February 2014 (UTC)
Well, I was translating the Beginners' Guide into Czech language short time ago. There are many link and references to those pages. So renaming the pages just because it looks better does not sound very appealing to me, because I will have to do it again. :-( Of course adding the new content and updating the current one sounds good. But just renaming pages not.
Chrabros (talk) 04:54, 18 February 2014 (UTC)
It's not just for "looks". Its more to do with practical aspects - current naming means that these pages will not be found if searching for e.g. "Help", and it also makes it a lot harder to reorganise as OSM evolves. Don't worry, I will move all translated pages too and page redirects are added automatically. --RobJN (talk) 12:02, 18 February 2014 (UTC)
Definitely OSM is more than contributing. But "the" beginner's guide currently is focusing on contributing. I think it's good to focus, however I don't mean that contributing is more important than other aspects of OSM. One could solve this issue through renaming from "beginner's guide" to "beginner's guide - contribute" or whatever clarifies that this is only one aspect of OSM. --Cantho (talk) 03:19, 20 February 2014 (UTC)
Aseerel4c26, I don't feel good with the idea to delete the guide and replace it with "ordinary" pages, because the guide fits the special needs of beginners. But go ahead and propose a guide containing other pages to replace the beginners' guide, we will see :) --Cantho (talk) 03:19, 20 February 2014 (UTC)

Why not establish a coherent layout for guides in this wiki, including a guideline on how to group the pages? This would prevent us from re-discussing the same question again and again for each guide. In addition, a common layout gives a better onboard experience to users. If this sounds good to you, I will create a corresponding proposal on wiki organisation. --Cantho (talk) 03:19, 20 February 2014 (UTC)

The following guides exist until now (please add if some are missing), with varying layout/ grouping of pages:

I prefer tabs like in GPS, but using templates of course, for the following reasons:

  • The layout is attractive and coherent with the main page regarding the italic text and image on top, thus communicating that this is a special page regarding navigation.
  • You avoid having two navigation boxes like in OSM Map On Garmin. Instead, there's a clear top menu with submenu below for every page. The submenu is created automatically since it's the usual wiki page content box.
  • The number of sub-pages is limited because the top menu is horizontally arranged. This helps to keep the guides clear and focused.

--Cantho (talk) 03:19, 20 February 2014 (UTC)

Good idea to look at existing approaches. As mentioned in an old discussion above, there's a bunch of other attempts at guides. These are all single pages though, which obviously is one way of simplifying the navigation! : PdfManual, South Korea Mapping Guide, Running Stitch Pecha Cucha words, User:Detectist/OSM Mapping (Using Potlatch) for Dummies, User:Johnwhelan/How it works. I think those last two point the way to an interesting wiki organisation approach, discussed a bit more here. Rather than stressing about duplication, we might encourage people to write their own beginners guide, provided they keep them in their separate user scratchspace on the wiki. Taking that to its extreme, we might abort all attempts at collaboratively writing a beginners guide, and just make a list of individual documentation initiatives (including off-wiki initiatives such as That's a blue skies idea, but it's the sort of conclusion I'm tending towards after puzzling over the wiki beginners guide challenge for years now. -- Harry Wood (talk) 12:50, 20 February 2014 (UTC)
Why do the last two point the way to an interesting wiki organisation approach? Btw, putting everything on one page would mix the content of, for example, the beginners guide too much I think. --Cantho (talk) 05:49, 21 February 2014 (UTC)
Yeah I wasn't suggesting we take the current beginners guide and put it all on one page. Just saying there's quite a few other places where people have written guides, if we include these single page ones. That's not a comment on how to organise navigation. It's just the point that... if you're making a list of guides... there's quite a lot of them.
It's worth noting that there's lots of guides because it's proof that different people want to explain the project in different ways. A single wiki beginners guide will never have chapters organised in a way which pleases everyone. It's also important in relation to the discussion about page naming and duplication. Think about this for example. An early version of the beginners guide was largely written by User:ben, and he's been unhappy with some recent changes to it, so an interesting way to deal with that might be to have a fork of the guide from a couple of years back, copied to "User:ben/Beginners' guide". It becomes a documentation resource which he's more explicitly under control of (but he might invite others to contribute still) . And the current Beginners' guide might be moved somewhere else to label it so that it's not trying to be the one and only beginners guide. ...but anyway. You're just interested in discussing the template tabs approach to use, so feel free to ignore my ramblings.
On the topic of navigation, I agree tabs would be good, mainly because, as you say, "The number of sub-pages is limited because the top menu is horizontally arranged". Limiting the guide to fewer pages would be great, if we can figure out a way of doing that. In fact I deliberately named the side menu as Template:Beginners Guide Header with intention of turning it into tabs at some point.
-- Harry Wood (talk) 10:33, 21 February 2014 (UTC)

Tabs is a hard thing to do for the beginners guide as there are too many to fit in the horizontal space. I've been playing around and have settled on something that I think works well (this is version 2, the first got scrapped as I didn't like it at all). Let me know what you think. It's live on Beginners' guide only at the moment. --RobJN (talk) 21:24, 13 April 2014 (UTC)

Hm, I think the expanded list of pages takes really a lot of space. Without expanding it, there's a lack of overview. And the green background is really strong. Probably it's to distinguish the navigation part from the text and to construct a common look and feel, but I would prefer a more discreet variant. Tabs work quite good. I wrote an example containing only the main pages. The subpagges would merge into the corresponding main pages. What do you think? --Cantho (talk) 07:28, 14 April 2014 (UTC)
A distinct look was the aim as it will make it clear when people follow a link (e.g. to GPS) that does not form part of the guide. Yes, the list is hidden by default but can easily be expanded. On the other hand tabs do not show the full guide structure (as subpages are not shown). Can you make an example of how a sub-page would look when using tabs. For example, the Beginners Guide page. Cheers. Let's see what others have to say about these two designs. --RobJN (talk) 11:59, 14 April 2014 (UTC)
That's right, the tabs navigation doesn't show the current subpages. They would be subsections in the articles. If you want to improve the guide and you want to do it with your proposed layout, I don't stand in your way :) But here's an example page containing your desired subpage. One would need to rewrite the article a little bit, it's just to give an idea on how subpages/ subsections could be realized. Best wishes --Cantho (talk) 16:27, 15 April 2014 (UTC)
From Beginners'_guide I get to Beginners_Guide_1.0 which contains Lorem ipsum text... Please do not use the main, LIVE, pages for layout and proposals. :-( Sorry, cannot look into more but this caught my attention... --Aseerel4c26 (talk) 22:45, 14 April 2014 (UTC)
moved it to a proposal page. --Cantho (talk) 16:27, 15 April 2014 (UTC)

Some mess in 2015

I was just taking a look at the Beginners Guide again. Haven't done so in while and ... geez it's a mess. I mean more so than it has been in the previous 10 years I've looked at it!

I see quite a lot of issues created by User:Xxzme at the moment. Xxzme had to be banned from the wiki due to his fast-paced messing up of wiki pages, and aggressive communication style. It seems his tornado of mess making has swept through the Beginners Guide several times over.

I see one discussion about the beginners guide, for some reason over at Talk:Contribute map data#Can we have the beginners' guide pages back please?. In there User:SomeoneElse sums it up as "It just reads like someone's thrown a bunch of links onto the page without any thought given to how someone will read it or how new contributors come to this page and how they will navigate through it".

Well maybe it has been tidied a bit since then but I see these pages he set up and linked very prominently from the beginners guide front page: Data_collection_using_your_memory#Tips, Data_collection_using_short_descriptive_comments#Tips, Data_collection_using_satnav_tracelog#Tips ... all of which seem to be a total mess. And he also seems to have littered the rest of the content with gobledegook badly constructed sentences.

Let's be bold and tidy up some of that now.

-- Harry Wood (talk) 01:40, 20 December 2015 (UTC)

How feasible would it be for people create tidied versions underneath their own userspace? I think of a few ways of creating a more followable "beginners' guide", but any of them would be difficult to do in one go, and to try and do it piecemeal would mean that in the meantime we had an even worse guide than we have now and we'd be wasting the time of translators on intermediate versions. I've been planning to have a go at something like this for a while now, but it's been put off for lack of time / weather too good to stay indoors.
(edit: Just spotted you had the same idea 5 years ago! )
--SomeoneElse (talk) 09:51, 21 December 2015 (UTC)
Indeed! Never quite followed through on the idea.
I mentioned above that this guide (or an earlier version of it) could be forked to "User:ben/Beginners' guide", because I believe he was the main man behind the original 5 step structure of this guide, and also this image: File:First Page2.PNG which obviously provided a framework. The english guide no longer has those headings "1 Gather, 2 Upload, 3 Edit maps, 4 Edit data, 5 Render maps", but we can still see a bit of hangover from that, and the translations do still have that. It's not the structure I would lay out for a "beginners guide".
That's the fundamental difficulty we've always struggled with. When you author a beginners guide, you tend to spin the narrative in your own way. You choose the key headings in a particular order. Collaborative authoring of a compact guide is ... a struggle. Over the years we've effectively tried to have hundreds of people agree upon the best order to tell the story in. Largely hopeless. I wouldn't say it's a total failure. There's an inertia of the original body of text, and the translations, which made it hard work to try to "fix" the structure, and that is perhaps a good thing, because if everyone tried to "fix" it to align with their own thinking it's would be even more of shifting blob of chaos. But of course that also means there's quite a few people dissatisfied by this one central wiki guide.
Proposed solution: What I actually want to do with this, is declare a ban on centralised "beginners guide" wiki pages. I want to say... *trumpet noise* henceforth we shall not have a "beginners guide" wiki page. Or more broadly, I propose a wiki policy: You're no longer allowed to initiate new wiki documentation which "bags the central ground" naming itself *the* beginners guide/introduction.
Instead we will have a central wiki list of documentation resources, some of which may be wiki-based, but named in a less "centre-bagging" way. Under user pages is one way. I'm thinking the list might live on a page title like "Guides". So now that bags the centre-ground. It's the thing everyone links to. And the list would have quite a few options. Potentially confusing for a beginner, but we'd take an approach like on the Editors page where we agree (somehow) upon which are our current favourite recommendations to appear more prominently at the top of the page.
This rule may or may not be applied in other language namespaces. Leave it up to them. The current beginners guide translations would simply link to the new, less centre-bagging, name for the english version.
And what would the new page name be for the current Beginner's Guide? That's the remaining question. We could try naming it according to this characteristic structure. We could call it the "The Gather Upload, Edit, Render Beginners Guide". But that name is a bit too long. We're looking for a name which would have subpages, so needs to be a bit more compact than that. Maybe the "GUEER Guide" :-) not sure.
As I say the translations could cross link into this new home. Obviously initially the "Beginners Guide" wiki page would redirect to the new home too, but ultimately "Beginners Guide" would be changed to just redirect to the new "Guides" list page.
And in this way a new less stiflingly-centralised wiki beginners guide era will be born!
BUT... having said all that, I think there's value in working to tidy up Xxzme's messy changes to our current centralised guide. Even if we adopt my proposal, this content will live on, pages will need to be moved (some of which are currently better deleted in my opinion) so fixes/tidying is welcome.
-- Harry Wood (talk) 02:23, 22 December 2015 (UTC)

On the more short-term clean-up, i'm looking at deleting this family of new pages: Talk:Data collection using your memory. I will start by de-linking them from this main page for a start. -- Harry Wood (talk) 20:43, 22 December 2015 (UTC)

Guide 2017 cleanup

The guide is super messy and I took the liberty to clean up the very obvious parts without consulting anyone. I also added obviously missing sections (e.g. I explained what tags are). For more radical or non obvious changes, I will consult the community via this talk page.

My current todo

  • Rescan the guide, look for things to improve, update, or omit. (tracelog page could use some changes, I think), and update this todo.
  • Make this more "Smartphone friendly" by adding appropriate links, app links, and remarks. Presumably many newbies have GPS-enabled smartphones.
  • Uppercase/lowercase consistency, and page titles consistency (currently some are bare titles, and some are section numbers e.g. compare Beginners_Guide_1.1 and See_your_work_and_start_using_data

All comments are welcome!

-- SwiftFast (talk) 07:57, 28 April 2017 (UTC)

I think all numbers should be removed from page names, replaced by a more descriptive title of the topic of each page. This does not help restructing/upgrading the content for the new best practices or tools, and make links more obscure to edit. Some topics may be removed and kept only archived in their category, even if they are no longer referenced by the navigation TOC. — Verdy_p (talk) 22:07, 28 April 2017 (UTC)

I think the guide should be restructured as follows

  • Join the community (signup and communication channels)
  • Understand OSM data (explains elements and tags)
  • Learn the basics of one of the editors (links to iD, poltach, and JOSM's guide)
  • Mapping techniques
    • Armchair
    • Outdoors

-- SwiftFast (talk) 12:23, 30 April 2017 (UTC)


I have compacted the guide. Here's a full summary of changes:

  • Removed lots of needless information - No one cares about the minimum temperature a pencil works at, and beginners don't care about multiple monitors, etc.
  • Generally abbreviated some parts, I don't think we should be assuming the user is dumb. e.g. (don't use 10 year old memories because they might have changed, paper works at all conditions but protect it from water).
  • "Mapping technique" was largely overlapping with "sources of information", so I removed the latter and updated "mapping techniques"
  • Removing the needless information gave me space. So I moved the important bits of the subsections to the main sections.
  • The subsections were removed, because they didn't add much value anymore. Everything they say is now written in the main sections. (let me know if anything was lost)
  • Added some useful mapping techniques. (The page is now big, so I enabled its TOC. I like abbreviation but I can't find a way to make it shorter without missing important bits. But I hinted that not all of it has to be read).
  • Explained what tags are.
  • Perhaps the "general tips" subsection and some other subsections should be re-added once cleaned up.
  • I reordered the pages. The rationale is that elements and tags should be explained *before* reading "mapping techniques", otherwise people read about tags and so on without knowing what they are, and without having a general idea of how mapping works.
  • I don't think we should write editor-specific guides - I linked to the already written editor guides instead. (Exception: Very short instructions like enabling aerial in JOSM)
  • Several more changes. (link to news and communication channels, etc).

I apologize for the "shoot first, ask questions later" course of action. I realize the guide has been misleading for years, and I figured the best thing to do would be to quickly turn it from "horrible" to "somewhat readible" with minimal discussions (discussions have been taking place for years). Now that it's in a better state, my changes will be slower and based on community discussions.

More todo:

  • Merging the last two pages into one "what's next".
  • At this point I need comments, I feel I'm venturing too far without feedback.

Related read: Talk:Data_collection_using_your_memory

-- SwiftFast (talk) 07:03, 2 May 2017 (UTC)

Does LearnOSM make the guide redundant?

Title says it all. -- SwiftFast (talk) 14:01, 2 May 2017 (UTC)