Backport materials and illustrations to JOSM wiki? #162

Open
d1g opened this Issue Mar 13, 2016 · 4 comments

Comments

Projects
None yet
3 participants
@d1g

d1g commented Mar 13, 2016

Hello Mapbox(ers)!

There a number of concerns why I'm suggesting this:

  • josm wiki is integrated within JOSM editor (this is what user(s) see when they are offline)
  • every JOSM user will have access to it (even they haven't heard about Mapbox company) Yet ;)
  • it near to impossible to outperform JOSM developers in creating new tools vs keeping docs up to date; if we spread efforts we all loose
  • this repository (mapbox/mapping) has no option for localization (little to no facilities for translation ATM)
  • there no chance to re-explain interface in new tutoring materials 1 2 3 - even some pages still incomplete, there so many hours were put to them (no offense, but no way any company could repeat this)
examples

I mean, it would be nice to describe JOSM in one place, not in every individual company: a correct, but incomplete guides - probably not what we want for our users/mappers. As far as I can see, It doesn't matter what is target audience: a Mapbox employee or a real mapper, one day they will need exhaustive info on some topic: how to correct validation errors

I haven't seen a single guide that explains status bar as well as is it should: https://josm.openstreetmap.de/wiki/Help/StatusBar or a search interface: https://josm.openstreetmap.de/wiki/Help/Action/Search or expert mode https://josm.openstreetmap.de/wiki/Help/ExpertMode

@planemad

This comment has been minimized.

Show comment
Hide comment
@planemad

planemad Mar 14, 2016

Contributor

@d1g thanks for bringing this up. Lets be very clear that the intention of these mapping guides is not to replace the JOSM wiki which is the right source for the latest software documentation.

These mapping guides are just a condensed version of all the existing guidelines and best practices for ease of access for our data team internally.

All the material is cc-0, so please feel to reuse/backport any of the materials to update the JOSM/OSM wiki. Let us know how we can assist to make this easier

Contributor

planemad commented Mar 14, 2016

@d1g thanks for bringing this up. Lets be very clear that the intention of these mapping guides is not to replace the JOSM wiki which is the right source for the latest software documentation.

These mapping guides are just a condensed version of all the existing guidelines and best practices for ease of access for our data team internally.

All the material is cc-0, so please feel to reuse/backport any of the materials to update the JOSM/OSM wiki. Let us know how we can assist to make this easier

@planemad planemad closed this Mar 14, 2016

@planemad planemad reopened this Mar 14, 2016

@d1g

This comment has been minimized.

Show comment
Hide comment
@d1g

d1g Mar 14, 2016

@planemad, thanks! My progress, may contain mistakes

Plugins are not documented: simply install some plugin, hover mouse over button(s) on the left or main menu items (top) and then press F1.

If there no help, then it means something should be written here (within embedded browser: button in top right corner used to edit wiki page using browser).

If we were documenting tools this way, then we could simplify all instructions to: 1. here is first edit guide, 2. if you have questions about JOSM - press F1 over element 3. custom tasks are here ...

You could assist by documenting plugins you use in your workflows first (for example Mapillary plugin): 1 2 3

d1g commented Mar 14, 2016

@planemad, thanks! My progress, may contain mistakes

Plugins are not documented: simply install some plugin, hover mouse over button(s) on the left or main menu items (top) and then press F1.

If there no help, then it means something should be written here (within embedded browser: button in top right corner used to edit wiki page using browser).

If we were documenting tools this way, then we could simplify all instructions to: 1. here is first edit guide, 2. if you have questions about JOSM - press F1 over element 3. custom tasks are here ...

You could assist by documenting plugins you use in your workflows first (for example Mapillary plugin): 1 2 3

@seb-1204

This comment has been minimized.

Show comment
Hide comment
@seb-1204

seb-1204 Mar 20, 2016

@planemad I thank you very much for your effort on this, however I think you are avoiding @d1g concern with this. Yes you say this is your 'internal guide/best practice' but at the same time you have invested time and resources to summarise and condense the best practice in the osm world. I would think that the wiki would be the better place to reach more mappers and spread adoption and knowledge of these best practices.

@planemad I thank you very much for your effort on this, however I think you are avoiding @d1g concern with this. Yes you say this is your 'internal guide/best practice' but at the same time you have invested time and resources to summarise and condense the best practice in the osm world. I would think that the wiki would be the better place to reach more mappers and spread adoption and knowledge of these best practices.

@d1g

This comment has been minimized.

Show comment
Hide comment
@d1g

d1g Mar 20, 2016

@seb-1204, it's a more tricky question because (say, JOSM documentation) documents all 400+ hotkeys or all toggle dialogues, but not everyone needs everything.

Re-documenting (say, JOSM features) is wrong, but combining right subset of links to a complete JOSM documentation - is correct. Improving navigation within JOSM wiki - is also correct (consider using feature X when you are using B, D but A is not available).

As bad example I would use http://learnosm.org that forces you to read about fieldpapers and GPS, but neither of them is necessary or required to start OSM contribution. People who use field pappers and GPS when imagery is available and was traced by local mappers are horribly under-perform in mapping. With dense infrastructure and many objects you will need photos and video.

It is faster to take a photo or vidoe, then to capture data using pen & paper.

When we talk about "best practice" (say, lanes), there a page about it at wiki: https://wiki.openstreetmap.org/wiki/Lanes. Based on edit history, I can say that it wasn't expanded as well as it should: 1 2

Some of information is US-only, but we can use region-specific paragraphs (similar to this page)

PS. I'm happy that we could simply reuse what Mapbox(ers) did for themselves without need to worry about license compliance and all that legal nonsense

d1g commented Mar 20, 2016

@seb-1204, it's a more tricky question because (say, JOSM documentation) documents all 400+ hotkeys or all toggle dialogues, but not everyone needs everything.

Re-documenting (say, JOSM features) is wrong, but combining right subset of links to a complete JOSM documentation - is correct. Improving navigation within JOSM wiki - is also correct (consider using feature X when you are using B, D but A is not available).

As bad example I would use http://learnosm.org that forces you to read about fieldpapers and GPS, but neither of them is necessary or required to start OSM contribution. People who use field pappers and GPS when imagery is available and was traced by local mappers are horribly under-perform in mapping. With dense infrastructure and many objects you will need photos and video.

It is faster to take a photo or vidoe, then to capture data using pen & paper.

When we talk about "best practice" (say, lanes), there a page about it at wiki: https://wiki.openstreetmap.org/wiki/Lanes. Based on edit history, I can say that it wasn't expanded as well as it should: 1 2

Some of information is US-only, but we can use region-specific paragraphs (similar to this page)

PS. I'm happy that we could simply reuse what Mapbox(ers) did for themselves without need to worry about license compliance and all that legal nonsense

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment