Talk:Beginners' guide

From OpenStreetMap Wiki
Jump to navigation Jump to search

Discuss Beginners' guide here:

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)

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)

I just moved old discussion that are no longer relevant to an archive subpage. --Push-f (talk) 09:14, 8 July 2022 (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)

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)

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)

In my opinion it does not because:
--Push-f (talk) 09:41, 8 July 2022 (UTC)

The link could be changed. The need for pull requests means every change gets another pair of eyes. --Andrew (talk) 18:43, 13 July 2022 (UTC)

Messy navigation and structure

I see the following issues with the current English Beginners' guide:

Every page starts with horizontal tabs

which however confusingly don't actually let you navigate the beginners' guide (for that you have to use the sidebar). So I think we should either remove the tabs, or convert the sidebar to tabs (as in the German beginner's guide).

The actual side bar (Template:Beginners Guide Header) currently contains:

Join the community
  1. OSM data explained
  2. Pick your mapping technique
  3. Uploading changes
  4. See your work and start using data
  5. Additional help and resources (optional)

I think it looks odd that "Join the community" is separate from the list, I'd expect it to be the list item number one.

Also it's very confusing that every 2nd page of the beginner's guide has some odd numbers in the page title:

  1. Join the community
  2. Beginners Guide 1.3 "OSM data explained"
  3. Pick your mapping technique
  4. Beginners Guide 1.4.2 "Uploading changes"
  5. See your work and start using data
  6. Beginners Guide 1.6 "Additional help and resources (optional)"

So I think it would make sense to get rid of these numbers (as has been suggested several times over the last decade on this talk page).

Lastly, I don't think that it's a good idea that the editors are listed on the page titled "OSM data explained". Chances are that beginners are looking for a list of editors and if no page of the beginner's guide says "editors" they might be confused as to where to find information about them. The German beginner's guide again does a better job by having a page titled "pick your editor" (DE:Bearbeitungsprogramm auswählen).

What do you think about these issues?

--Push-f (talk) 10:10, 8 July 2022 (UTC)

I obviously agree with most of your points since I maintain the German guide. I personally do not mind the numbers even though they do not make a lot of sense anymore. You can rename/move the English pages but you need to retain the redirects so the languages still link to each other. --Tigerfell This user is member of the wiki team of OSM (Let's talk) 13:36, 13 July 2022 (UTC)
I also agree. With the current navigation vice versa would have make more sense (beginners' guide menu horizontal, help menu in box aside). Perhaps if you update it, you may also take into account mobile devices and use flex boxes; e.g. something like Sandbox&oldid=2359992? --Chris2map (talk) 10:37, 16 July 2022 (UTC)

Remove HelpMenu (tabs)

I'd like to remove the {{HelpMenu}} (tabs menu) from all the Beginners' guide pages. IMO this menu is not necessary on the Beginners' Guide and using the Beginners' Guide is easier the less menus are displayed. In addition the HelpMenu (in its current form) doesn't work well with small mobile deviceses and breaks the readability on small screens to the rest of the content and the whole page. If one searches for general help, there is always the Help link to the left in the wiki main menu, which leads directly to pages with the HelpMenu. Wouldn't this be OK? --Chris2map (talk) 13:00, 24 July 2022 (UTC)

Meanwhile I stitched a test version of {{Tabs}} without table elements but with css flex to support narrow screens like on mobiles: User:Chris2map/Sandbox&oldid=2360355 and {{Tabs flexible}}. It seems to work, see Sandbox&oldid=2362587. Nonetheless the question, if the HelpMenu is needed in Beginners' guide. --Chris2map (talk) 16:55, 25 July 2022 (UTC)