Out of curiosity, is contributing to documentation a part of HOTs training 
curriculum? Perhaps better instructions actually on LearnOSM could help bridge 
the gap? GitHub doesn't need to be anymore geeky that OSM, right? 

Best,
Alyssa.

On Jul 25, 2013, at 9:26 AM, Pierre Béland <pierz...@yahoo.fr> wrote:

> 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_ma...@yahoo.com>
> À : Alex Barth <a...@mapbox.com>; Harry Wood <m...@harrywood.co.uk> 
> Cc : "hot@openstreetmap.org" <hot@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 <a...@mapbox.com>
> To: Harry Wood <m...@harrywood.co.uk> 
> Cc: "hot@openstreetmap.org" <hot@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 <m...@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 <k...@maploser.com>
> To: Yohan Boniface <yohan.bonif...@hotosm.org> 
> Cc: "hot@openstreetmap.org" <hot@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.bonif...@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@openstreetmap.org
> > http://lists.openstreetmap.org/listinfo/hot
> 
> _______________________________________________
> HOT mailing list
> HOT@openstreetmap.org
> http://lists.openstreetmap.org/listinfo/hot
> 
> 
> 
> _______________________________________________
> HOT mailing list
> HOT@openstreetmap.org
> http://lists.openstreetmap.org/listinfo/hot
> 
> 
> 
> _______________________________________________
> HOT mailing list
> HOT@openstreetmap.org
> http://lists.openstreetmap.org/listinfo/hot
> 
> 
> 
> _______________________________________________
> HOT mailing list
> HOT@openstreetmap.org
> http://lists.openstreetmap.org/listinfo/hot
> 
> 
> _______________________________________________
> HOT mailing list
> HOT@openstreetmap.org
> http://lists.openstreetmap.org/listinfo/hot
_______________________________________________
HOT mailing list
HOT@openstreetmap.org
http://lists.openstreetmap.org/listinfo/hot

Reply via email to