[HOT] [Reflexion] Where does LearnOSM end, where does the OSM wiki begin?

Thu Jul 25 10:21:52 UTC 2013

One key difference between the beginning and advanced materials is the story that the set of tutorials tells. For the beginning materials, this is the core story of contributing to OSM. The advanced, a more grab bag of advanced techniques you need. What exactly can you do by following those tutorials? If you don't already understand the technology, I don't think it's clear why you'd bother. 

Another way to organize advanced techniques is through short tutorials, that reference the raw skills of the current guides, but are more direct to purpose. Things like "Organize a Campaign", could touch on presets, on the tasking server, on quality assurance. Another, "Publish a Map", could touch on Extracts, PostGIS, TileMill (which already has great tutorials). So the tutorial link to more advanced manuals, but try to explain the point better.

Wherever advanced materials live, there needs to be a commitment to update and maintain them. Fact is, some of the Advanced Materials are already leagues ahead of documentation in other places. For example, Tagging Presets (which might all be made redundant by the visual tag chooser, but anyway). Can we make an effort to move these over?

http://josm.openstreetmap.de/wiki/TaggingPresets

https://docs.google.com/document/d/1khaW1pFEzaQ338NQlMEeGXP3531XjayAxdLvyhpkU_w/edit

Github really does seem ideal for a lot of this stuff. How much easier has it made translation? I still have some things to contribute to the Beginner's Guide, and a pull request gives the maintainer a chance to keep it high quality. The ability to easily print, we need this for everything.

-Mikel

* Mikel Maron * +14152835207 @mikel s:mikelmaron

>________________________________
> From: Alex Barth <alex at mapbox.com>
>To: Harry Wood <mail at harrywood.co.uk> 
>Cc: "hot at openstreetmap.org" <hot at openstreetmap.org> 
>Sent: Wednesday, July 24, 2013 4:51 PM
>Subject: Re: [HOT] [Reflexion] Where does LearnOSM end, where does the OSM wiki begin?
> 
>
>
>+1 for at least keeping the main purpose and the main focus of LearnOSM on the beginner's guide. Also from a user interaction perspective, i. e. keep the entire experience focused on getting people started on OSM. Place small links for the advanced folks. Where advanced materials live - Wiki or LearnOSM really depends a lot on HOT's needs.
>
>
>I'll throw one important consideration into the discussion though: Brand & quality. I'd recommend focusing only high quality materials on LearnOSM and throw out anything where there's a doubt that there will be bandwidth to maintain long term. You want to make sure that your LearnOSM users can expect a certain level of accuracy, freshness and quality from your tutorials.
>
>
>Alex
>
>
>
>On Wed, Jul 24, 2013 at 9:53 AM, Harry Wood <mail at harrywood.co.uk> wrote:
>
>OK here's brain fart on the wider topic of documentation, particularly introductions to OpenStreetMap.  I should do this as a blog post or something really. Consider this a preview to read if you're interested.
>>
>>
>>
>>
>>I've given OpenStreetMap documentation a lot of thought over the years as I've been involved in wrangling the OSM wiki, and generally had a deep interest in wiki communities (it's how I got into OSM in the first place)  Obviously documentation has popped-up on other websites. LearnOSM.org is one example but actually there's quite a lot this. MapQuest wrote a beginners guide: http://developer.mapquest.com/web/products/open/tools/guide  Potlatch2 has several pages of 'help',  and iD editor has too plus a 'walkthrough'.  And when you consider smaller more targeted bits of documentation, there's *loads* e.g. The little tutorials Richard Weait publishes: http://weait.com  Countless other bits like that out there.
>>
>>
>>Doing documentation the wiki way means you can collaborate easily this works really well for some types of technical documentation where the more detail you have the better. A good beginners guides though, is as much about what detail you leave out as what you put in. Also it can be about telling the story in a compelling way, with a particular voice and a beginning-to-end narrative. In theory there's no reason why we can't achieve that on a wiki. We just iterate to remove detail and fix the narrative right? Well it can work, but it can be hard justifying *removing* stuff that people add. I've done this here for example: http://wiki.openstreetmap.org/wiki/Talk:JOSM/Advanced_editing   Depending on the extent to which you want to "tell a story", it can easily be that your documentation is not suited to collaborative authoring at all. We've always struggled with the 'Beginners guide' on the wiki because it's tough to agree on an overarching vision for
 how to structure it (although I haven't given up yet!)
>>
>>
>>Obviously at the other extreme there's a single-author documentation published read-only on a website.  Collaborative authoring on git(hub) is maybe just somewhere in between. It's as openly editable as a wiki in theory, but the mysteriousness of git and markdown etc presents a technical barrier, meaning fewer people editing... and that's sort of a good thing. Obviously there's also an "approval" step which creates a different dynamic to a wiki, and puts some people off contributing. I don't think git proponents should pat themselves on the back for inventing a new authoring approach too much. It's really just a *more difficult* version of a wiki. And by being more difficult it gains the *benefits* of fewer authors. Having said that, git also presents a branching concept. Normally you'd think of these two things as something very different: A) "I'm going to contribute to improve this document"  B) "I'm going write my own version of this document
 because I can do it better".  But git blurs the distinction, which is interesting at least in theory. In practice we don't see lots of people publishing their own version of learnosm.org .
>>
>>
>>In the grand scheme of things, people *will* document OpenStreetMap using multiple approaches. There's no stopping this. They will even document OpenStreetMap using the *same* approach but in different ways. Lots of duplication. It's particularly silly when people decide to write yet another introduction to OpenStreetMap on the wiki without explanation. 
>>
>>
>>Maybe the explanation is the key actually. If you can explain your different approach or different target audience, then maybe you can justify why another documentation resource needs to exist. If you can explain how to contribute, then maybe you can motivate others to join in and de-motivate others from creating even more duplication. LearnOSM.org has a good bit of meta-documentation like this here: https://github.com/hotosm/learnosm/blob/gh-pages/CONTRIBUTING.md   Alternatively if documentation exists because it's done *your* way, and you are the only author, maybe that's OK too. Again this could be displayed as meta-documentation somehow.
>>
>>
>>This documentation of the documentation is one piece of the puzzle. It might be good to then take all of that and build a centralised catalogue of different documentation resources. Maybe Communications Working Group could attempt to tackle this. It might serve the purpose of helping readers find the documentation they need. It might also direct contributors to contribute where it's most welcome. It could also include rating the documentation on how "finished" it is, and things like whether or not it can be downloaded as a self-contained PDF.
>>
>>
>>Another thing which complicated matters is interlinking. We hit this with the wiki beginners guide, and it's a bit like this question of advanced materials for LearnOSM.org.  For what stuff should we just link to the wiki, and what should brought into the fold as part of the self-contained documentation? I think in both cases we should be clear about scope, and for everything else embrace the power of the hyperlink! ...but maybe in some stylised way which makes it clear "you are now leaving the document".
>>
>>
>>
>>phew!
>>-- End of long meandering email --
>>
>>
>>Harry
>>
>>
>>
>>
>>
>>________________________________
>> From: Kate Chapman <kate at maploser.com>
>>To: Yohan Boniface <yohan.boniface at hotosm.org> 
>>Cc: "hot at openstreetmap.org" <hot at openstreetmap.org> 
>>Sent: Tuesday, 23 July 2013, 19:41
>>Subject: Re: [HOT] [Reflexion] Where does LearnOSM end, where does the OSM wiki begin?
>> 
>>
>>Hi Yohan,
>>
>>A couple thoughts:
>>
>>1. We have contractual obligations to publish those materials where
>>they currently are meaning as curated documentation on a website. For
>>example the Scenario Development for Contingency Planning (SD4CP)
>>program uses both the Beginner and Intermediate documentation as part
>>of our program. That documentation was specifically paid for through
>>the SD4CP program. The advanced materials were actually paid for
>>through the program as well, but currently are not in use.
>>
>>2. Yes Github is not open-source but git is, meaning we can move and
>>clone the materials at anytime. The InaSAFE/QGIS materials in SD4CP
>>are published through Sphinx instead also using git.
>>
>>3. I think there is a place for "finished" documentation. There are
>>plenty of places in the wiki that are very confusing for even
 advanced
>>users.
>>
>>4. Maybe the advanced materials could be moved to the wiki, but I'd
>>like to hear from other projects that are specifically uses LearnOSM
>>and contracted to do so.
>>
>>-Kate
>>
>>
>>
>>On Tue, Jul 23, 2013 at 10:45 AM, Yohan Boniface
>><yohan.boniface at hotosm.org> wrote:
>>> Hi Hotties,
>>>
>>>
>>> LearnOSM does a very great job in catching the newbies, giving them good
>>> basis to start contributing to OpenStreetMap. The new design powered by
>>> Mapbox is awesome, modern, and very attractive.
>>> LearnOSM is with no doubt, a very important pillar of OSM.
>>> Nevertheless, I have some concerns about its perimeter.
>>> Here is my point: as I've stated, I have no problem about the function of
>>> LearnOSM for newbies, but I doubt that it is a good way
 of storing more
>>> advanced
 learning material.
>>> OSM has already a wiki for this. And the wiki *is* part of the toolbox of
>>> learning for an OSM editor. And thus isn't that the final step of LearnOSM
>>> should be to guide the now-no-more-newbie to the wiki?
>>>
>>> I see some disadvantages in using LearnOSM instead of the wiki for
>>> *intermediate and advanced* materials:
>>>
>>> - the workflow for publishing/updating the data is centralized: only the HOT
>>> Github members (I am one) have the authorization to publish things
>>>
>>> - the workflow for creating and updating the documentation is much harder:
>>> using git is not like editing a wiki, and recent discussions on IRC (in
>>> #hot), emails, and on Github issues shows that this is an obstacle for some
>>> of us
>>>
>>> - we should avoid creating a monoculture based on non open source and non
>>> community based technologies, and, just a reminder,
 Github is not open
>>> source
>>>
>>> So here is what I suggest:
>>>
>>> - stop publishing intermediate and advanced chapter through LearnOSM
>>>
>>> - move the "Editing the wiki" chapter as last chapter of the beginners
>>> section
>>>
>>> - start contributing and focus to the wiki again, adding the advanced
>>> chapters, and translation, and everything
>>>
>>> - (why not) revamping the wiki look, to make it a little bit more attractive
>>> and modern (yeah, long process, full of trolls in talk@, etc., but that's a
>>> community way of growing, and that's what OSM is, a community).
>>>
>>> Of course, this is just my opinion.
>>>
>>> Again, LearnOSM is a very nice and important project, I'm just wondering
>>> about using it for advanced materials.
>>>
>>> Thanks for reading, please discuss,
>>>
>>> Yohan
>>>
>>>
 _______________________________________________
>>> HOT mailing list
>>> HOT at openstreetmap.org
>>> http://lists.openstreetmap.org/listinfo/hot
>>
>>_______________________________________________
>>HOT mailing list
>>HOT at openstreetmap.org
>>http://lists.openstreetmap.org/listinfo/hot
>>
>>
>>
>>_______________________________________________
>>HOT mailing list
>>HOT at openstreetmap.org
>>http://lists.openstreetmap.org/listinfo/hot
>>
>>
>
>_______________________________________________
>HOT mailing list
>HOT at openstreetmap.org
>http://lists.openstreetmap.org/listinfo/hot
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/hot/attachments/20130725/8a5abdd8/attachment-0001.html>