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

[Dirk Stöcker]

On Sun, 4 Oct 2009, Rolf Bode-Meyer wrote:

> There was a post just yesterday where some people agree that they just 
> push the buttons at random until the conflict is either resolved or the 
> changes completely messed up.

Users always request better documentation, but when there is a good 
documentation it is not read usually.

> 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. 
Most of the docs can be written without knowing how the things work in 
detail:
  - describing appearance and situations
  - making screenshots
  - showing different situations and ways to handle them
Asking specific questions here like "what does that button do" can help to 
solve troubles and the explanations can be copied into a doc.

Till now I was not able to convince one single person to really update 
JOSM online docs (with more than typos), so it seems doing that work is 
not worth the effort.

> Sure a dialog that needs no explanations at all would be best, and I 
> understand that some things just aren't simple enough for simply 
> pressing a button. But please also keep the actual users in mind when 
> designing the UI, at least give the buttons some meaningful tooltips.

Best is always when there are specific suggestions how a dialog can be 
improved so it is better understandable.

Ciao
-- 
http://www.dstoecker.eu/ (PGP key available)