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

Thu Jul 25 13:55:03 UTC 2013

Have you tried http://prose.io ? It's a simple GUI around editing gitpages.

* Mikel Maron * +14152835207 @mikel s:mikelmaron

>________________________________
> From: Pierre Béland <pierzenh at yahoo.fr>
>To: Mikel Maron <mikel_maron at yahoo.com>; Alex Barth <alex at mapbox.com>; Harry Wood <mail at harrywood.co.uk> 
>Cc: "hot at openstreetmap.org" <hot at openstreetmap.org> 
>Sent: Thursday, July 25, 2013 9:26 AM
>Subject: Re: [HOT] [Reflexion] Where does LearnOSM end,	where does the OSM wiki begin?
> 
>
>
>We are a few HOT contributors translating presently LearnOsm to french.  We have the capacity to rapidly translate the documents and the images.  But we are stopped by the Github Collaboration tools. We use these tools occasionnaly and do not master them well enough to reproduce adequately the LearnOsm directory structure in our account, "Push" the new documents to our account, copy on our computer, and once finish editing move this to our Github account and ask to "Pull" this to the master HOT/LearnOsm directory.  Every time we collaborate with this tool, we pass a lot of time to be lost in the maze of commands and directories. We have hard time to find where the images are stored. Not to say that we cannot visualize the result with the images incorporated.
>
>I think that those that use regularly the system do not
 understand how occasionnal users can be lost in this maze of commands and directory. This is a "Geek" system. Asking for help, we are invited to simply read the documentation wich do not help us to progress.  And teams on the field are waiting for this essential information for their current training sessions ...
>
>We have to think of ways to collaborate that take account of the various technical skills of the contributors. Those that contribute to the translation are not necessarily those that have the technical skills to play with "Geeks" tools like Github.
>
> 
>Pierre 
>
>
>
>________________________________
> De : Mikel Maron <mikel_maron at yahoo.com>
>À : Alex Barth <alex at mapbox.com>; Harry Wood <mail at harrywood.co.uk> 
>Cc : "hot at openstreetmap.org" <hot at openstreetmap.org> 
>Envoyé le : Jeudi 25 juillet 2013 6h21
>Objet : Re: [HOT] [Reflexion] Where does LearnOSM end,	where does the OSM wiki begin?
> 
>
>
>
>
>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
>>
>>
>>
>_______________________________________________
>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/a7e62a4c/attachment-0001.html>