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

[Alex Barth]

+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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/hot/attachments/20130724/2258578b/attachment.html>