[OSM-talk] Reporting bugs and documentation

[Richard Fairhurst]

Tirkon wrote:
> Richard Fairhurst <richard at systemed.net> wrote:
> >I honestly didn't know that the relation ordering issue was the  
> case until
> >last week when Frederik pointed it out on this list. I'm now told  
> there'd
> >been some prior discussion of it on talk-de but that doesn't really  
> help a
> >whole load. I'm very happy to fix the bug (although I don't use  
> ordered
> >relations myself, nor in fact did I write Potlatch's excellent  
> relations
> >code) but I do need to know about it first!
>
> Thank you for fixing and your detailed answer. :-) Did you fix the
> changing direction of a way within a route-relation described above as
> well? Which version do we have to await?

Hang on hang on hang on. I didn't say I've fixed it yet. This week I'm  
on deadline with the day job and shouldn't even be taking the time to  
write this message. Next week, or at the end of this week, I will  
look. It will be _incredibly_ helpful if someone writes a trac ticket  
describing the issue between now and then.

> At present you have to use both editors. Potlatch to make the faults
> and JOSM to find them. But nearly nobody does this.
>
> The problem seems to be, that the more expirienced users use JOSM and
> the Potlatchers are rather hushed within the community. I experienced
> that the answers to questions concerning editing complicated objects
> with potlatch are not known in the community. The only answer I hear
> is: "Use JOSM".

Hang on again. Two serious over-generalisations there.

First of all to say "Potlatch to make the faults and JOSM to find  
them" is way off. In my experience, more people fuck up relations with  
JOSM than with Potlatch. Two things seem particularly common: JOSM  
users merging ways (members of a relation) with other ways (not  
members) and not noticing - maybe JOSM's default display style doesn't  
visualise relations as clearly as Potlatch, I don't know - and more  
seriously, JOSM users wiping out entire relations due to some bizarre  
partly-downloaded behaviour.

I'm not for a moment saying that's a universal rule. It seems to be  
the case in the major relation use case that I edit (UK cycle routes).  
Clearly it isn't the case for the sort of editing you do. But you  
can't simply say one makes the faults and the other repairs them.

Secondly, when you say "the more expirienced users use JOSM and the  
Potlatchers are rather hushed within the community", you're missing  
the word "German" twice in there. I'm deadly serious. That does appear  
to be true in Germany: it certainly isn't true in the UK where quite a  
few of the most experienced users are Potlatch-only, and others use  
both JOSM and Potlatch.



I think most of the rest of what you say comes down to one simple point:

> The problem of damaging unwanted things without being aware, is a big
> one. [...]
> Would it be useful, to initiated a kind of "collecting-basin" at the
> wiki, where all the "unawares" are collected in order to be a
> guideline for all coders of editors? [...]
> By the way: The trac is not made for users without coding experience.
> [...]

As a project we suck at documentation.

Our documentation is beyond terrible. I'm amazed that anyone ever  
manages to get started with OSM, I really am.

We have a small number of programmers who willingly suffer the slings  
and arrows of outrageous fortune etc. etc. to write some pretty cool  
stuff. By and large, in my opinion, they think deeply about design,  
they care about ease-of-use, they are never satisfied. They aspire to  
professional-quality releases. We don't always get there, and in some  
places we're still a long way off, but there's a really good process  
of ceaseless improvement. If you compare any of the OSM software with  
the equivalent two or three years ago, the difference is immense in  
every single case.

Oh, how I wish I could say the same about the documentation.

There's a few good individual pages but they're wildly scattered over  
the wiki. The wiki doesn't really work for documentation - something  
can start off clear and simple, then a well-meaning individual comes  
and adds their own hobby-horse, then someone else, and before long a  
simple "beginners' guide" has turned into a 20 screen-deep pile of  
cruft. (Just as most pieces of OSM software have "maintainers" who  
exercise some quality control and design guidance, the docs need that  
too.) Meanwhile, important stuff remains unexplained because people  
write about what they like, not what others need.

Nothing in OSM (bar the licence finally getting sorted out :) ) would  
make me happier than for someone to write some really good docs.  
Attractive, clear, focused, liberally endowed with videos and howtos.  
You don't need to be a programmer - arguably it's better if you're  
not. And you certainly don't need to be one of our existing  
programmers who have got plenty to do already.

Go and register openstreetmapguide.org and _make_ _something_ _cool_.

cheers
Richard


P.S.

> >We're a _collaborative_ project, but that only works if you  
> collaborate!
>
> Many non native persons will be able to survive, if they have to speak
> english. But to describe (or read) such complicated stuff only with
> school-english and with nearly no experience in the dayly life is
> another dimension.

I welcome bugs in any language supported by Google Translate, plus Old  
Irish, Medieval Welsh, Old English and Old Norse. :)