[josm-dev] Please invest some time into documentation - especially confilict resolution

[Ulf Lamping]

Dirk Stöcker schrieb:
> On Sun, 4 Oct 2009, Rolf Bode-Meyer wrote:
> 
>>>> So please would those people who implemented conflict handling give
>>>> detailed explanations in [[Help/Dialog/Conflict]] which currently is
>>>> simply not helpful?
>>> You really need no programmer to write documentation.
>>>
>>> A good way to reach that goal would be to start writing that documentation
>>> and ask the developers to fix or continue wrong or missing parts only.
>> For JOSM I think most processes or dialogues are quite simple and
>> comprehensible. So only a few people need documentation and nobody
>> writes it.
>> Especially for the conflict stuff I think it really is needed and I'd
>> write that documentation - but I'm lost as many else seem to be here.
>> So assuming the one who developed it knows best how it works, I think
>> at least this time it's a job for a developer.
> 
> The problem is that these dialogs are Karl's design. He knows how they 
> work best and that also means all is very plausible to him (for me too 
> BTW). A very bad start when writing docs. 

Karl could simply write down in a few sentences how the common workflows 
are to be done. No fancy screenshots or text formatting, so it can be 
done in less than 10mins. BTW: When you try to write it down, you'll 
probably already found some design mistakes :-)

Put it on the wiki and announce it to this list (or maybe directly to 
talk?) - asking for testing AND wiki improvements. This way, 
beta-testers know how the new feature is supposed to work and are now 
able to notice discrepancies between docs and implementation (aka bugs).

(Side Note: This would have saved me a lot of very annoying time to 
figure out how the MapPaint Preferences Styles dialog is supposed to work!)

Everytime someone asks about that feature simply point him to the wiki 
url (important: provide the exact url!).

I have repeated experience, that this works much better than what we are 
doing now. And it's also much more fun for both developers and users.

> Best is when someone who does 
> NOT know how it was designed writes docs. The errors he makes and the 
> questions he asks are very valuable input for fixing design issues and 
> also the result will be much more a documentation for beginners.

Perfectly agree, that developers often don't have the skills to write 
good docs for beginners.

> So we again have a situation that many people have many opinions and all 
> sides say "you need to do it". Karl and all developers already did a lot. 
> I always think it's time for the others to show they also want to 
> contribute before I believe words like "We continue after you start".

Hmmmm.

We have a <F1> feature that a little number of people know, a wiki that 
a little number of people know and no real communication channel for 
people wanting to involve (talk ml is way too high volume).

Sounds like a communication problem to me!

Looking at [1] I don't have the feeling that all users are just lazy ...

Regards, ULFL

[1] http://wiki.openstreetmap.org/wiki/DE:JOSM/Anleitung