Sunday, 1 February 2009


I've exchanged some interesting messages with Gary from Nafferton (NaffChap). He's been adding some footpaths through various parts of the local area. His questions have just reinforced the fact that the documentation for the project is letting us down. We use a wiki to document stuff, which seems to be the norm now, but I'm not convinced that it is a good idea. The very fact that anyone can edit it is great and awful at the same time. The wiki pages are all over the place, the language, tone and emphasis varies hugely. There are conflicting entries in a few places. I have created a few pages and maintained them, but most pages don't seem to have an owner so they either languish in slow decline or get hacked hither and thither by people with conflicting ideas or points of view.

I have tried to tidy some pages, but have given up because of adverse comments and conflicting revisions from other people. Some really useful features like relations are largely wasted, partly because the documentation bounces back and forth as to how to use them. People who know about how the wiki works just add complexity by sticking templates here, there and everywhere, which overloads the poor little server. They think this promotes consistency, but that comes from the text itself, not the layout.

The mailing lists are useful, though you need a thick skin to venture into osm-talk, but most users will only look in the wiki. SteveC has suggested a wiki cleanup day ( I think he probably had a wicked connected-world phrase for it) and that will be a good idea, but is a wiki really a good place for straightforward documentation - not in my book because sooner or later someone will screw it up.

Speaking of books , some people in Germany wrote an OSM book - I wonder how good that is at getting beginners started. The advantage of a book is that no-one can fiddle with it when it's published. The disadvantage is that it goes out of date, and quickly in world like ours.

I want OSM to succeed, and I'm sure it will, but it will do it better if beginners enjoy the process rather than fret over how to get started.

Gary has added some footpaths and that has just reinforced an idea that a walker's map for Easy Yorkshire will be a good idea. It is a lovely place to go for a walk and a good map always helps.


Anonymous said...

I just started with OSM myself and agree the documentation is lacking, particularly for beginners.

My suggestion would be for a small number of starter pages, targeted by user goal, rather than by technology, since depending on your equipment and motivation you can approach OSM from very different viewpoints.

This should be the kind of thing that goes in the wiki but it appears there's some kind of social rift between people who want the wiki to document the current reality of the OSM technology, and those that want to use it to enforce the "right" way to do things (or at least their version).

You'd think both could co-exist and be clearly marked as such but instead it seems revert-wars and forcing your position on others are considered socially acceptable approaches.

So anyone trying to write such documentation would have to solve that problem first, or find another way.

Harry Wood said...

Yeah we'll have to get cracking with the wiki clean-up, although I'm not convinced that a clean-up "event" will work particularly well.

"I have tried to tidy some pages, but have given up because of adverse comments and conflicting revisions from other people." Don't give up! The wiki needs more sane balanced people straightening things out! There's so much clean-up to do, I find it quite overwhelming, but I guess part of the problem is that some people have lost patience with it.

When clearing up mess after a wiki dispute, it can help to use language like "It is widely accepted that...", so that you're not exactly forcing one point of view, but at the same time you're clarifying the way most people are doing things. In this way you can blow away wiki mess, and tip-toe around the controversial points.