+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 <[email protected]> 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 <[email protected]> > *To:* Yohan Boniface <[email protected]> > *Cc:* "[email protected]" <[email protected]> > *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 > <[email protected]> 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 > > [email protected] > > http://lists.openstreetmap.org/listinfo/hot > > _______________________________________________ > HOT mailing list > [email protected] > http://lists.openstreetmap.org/listinfo/hot > > > > _______________________________________________ > HOT mailing list > [email protected] > http://lists.openstreetmap.org/listinfo/hot > >
_______________________________________________ HOT mailing list [email protected] http://lists.openstreetmap.org/listinfo/hot
