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
