[OSM-dev] Documentation Improvement

[SomeoneElse]

On 03/10/2014 11:31, Vanya Jauhal wrote:
> I'm Vanya, from India. I'm interested in contributing to the OSM 
> documentation as a part of the OPW project. I have been in touch with 
> Kate, and with her help, been able to understand the OSM documentation 
> better.

There's certainly plently of opportunity for improvement in more than a 
few areas, including as you say the beginner's guide.  There are major 
issues with that (no mention of the main suggested beginners' editor, 
for example).

>
> Also, all beginners currently have to start with the OSM tasking 
> manager. So I plan to start working on that.

Well; HOT is only a small part of OpenStreetMap.  Most (perhaps 99%?) of 
OSM users never see the HOT tasking manager.  That doesn't mean that 
it's not important for those that do use it of course.

>
> I have listed my ideas as follows, and would love to hear your 
> feedback on it:
>
> 1. The OSM beginner's page can have an FAQ section, where we can add 
> some common issues faced by users and their solutions.

There have been a few goes at this over the years, in various places.  
You mentioned the beginners' guide in the wiki already:

http://wiki.openstreetmap.org/wiki/Beginners_Guide


The "welcome" page on the main site is supposed to draw people in as well:

http://www.openstreetmap.org/welcome


The "learnosm" guide:

http://learnosm.org/en/beginner/all-chapters/


and if we expand things to just beyond mappers, there's also the 
"switch2osm" site:

http://switch2osm.org/

>
> 2.Adding user comments to the documentation.

That might work better than the "wiki" approach to documentation where 
unless there's a conscious attempt to "garden" pages the result is a bit 
of a mess; it would allow people to get their POV across while not 
deviating from the main thrust of the page.

One other thing that I'd suggest is to think about improving the help 
available to users of iD - currently there's no way for users to find 
out how to do things:

https://github.com/openstreetmap/iD/issues/1971

It might also be helpful to look at the sort of things that people are 
asking for help about:

https://help.openstreetmap.org/

Questions there run the gamut from technical "how do I map" and "how do 
I use data" questions through to legal issues and others.

Cheers,

Andy