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

[Karl Guggisberg]

> This is like the improvements in history dialog. One trac ticket with a
simple suggestion caused Karl to make 
> the history dialog much more understandable. It's not always that easy,
but sometimes such hints can do miracles.
Agree completely. We benefit from as precise suggestions as possible.
Another example is this strange "Reload" button in the selection dialog
which got mentioned today on dev. I think it was there since ages but nobody
with svn access realized how useless it was unless somebody sent a short
email (a trac ticket would have been even better). Personally I also benefit
a lot from precise suggestions/defect reports provided by Avar. 

> No. All my experience shows that this is untrue. People either help or
they don't help.
This goes along with my experience but the interesting point is how to find
those who want to help. What do you have to do to attract people who would
like to improve JOSMs documentation? I think today they don't even know that
JOSM is looking for help. If we want documentation work to be done we should
promote it. We can mention it on the JOSM home page as sub project, we can
structure the work to be done, we can describe what we need, we can provide
one or two good examples and tell people that we need more of the same. We
can announce that we are looking for help on OSM dev, or on the german list
for translation, for instance to achieve some small goal until end of
october (i.e. complete documentation of the conflict resolution dialogs).

-- Karl 

-----Ursprüngliche Nachricht-----
Von: josm-dev-bounces at openstreetmap.org
[mailto:josm-dev-bounces at openstreetmap.org] Im Auftrag von Dirk Stöcker
Gesendet: Sonntag, 4. Oktober 2009 16:59
An: josm-dev at openstreetmap.org
Betreff: Re: [josm-dev] Please invest some time into documentation -
especially confilict resolution

On Sun, 4 Oct 2009, Ulf Lamping wrote:

> JOSM translation shows that users are taking care if the hurdle for a 
> first start isn't too high. Me feeling is that the help system

The number of translators is so low, that I fear that does not qualify as
real good example of user help. Also only about 6 languages are usually near
100%, the others are much below.

> 1. We need a josm-users mailing list. osm.talk (or local lists) are 
> too polluted, josm-dev is not the right place for non dev questions 
> (and "dev" probably prevents users from asking here). We currently 
> don't have a place for a "JOSM user community" that could handle lot's 
> of issues already at this place. Maybe we even need josm-users-de as 
> there are lot's of german only JOSM users?

I don't think there would be enough traffic for JOSM only users lists. The
normal talk list are probably much better for this purpose.

> 2. Add meaningful tooltips for all GUI elements. This is by far the 
> easiest and fastest way (beside a good GUI design) for people to learn 
> a new GUI (at least that's true for me). While a lot of places already 
> have useful tooltips, especially new GUI parts often missing this - 
> where it would be most helpful.

Here specific suggestions are required: What elements miss describing texts
and what should the texts tell. This falls in the same group like "Why do I
need to click this and that, clicking this would be easier". The answer
usually is: "Because nobody ever thought about it that way".

This is like the improvements in history dialog. One trac ticket with a
simple suggestion caused Karl to make the history dialog much more
understandable. It's not always that easy, but sometimes such hints can do
miracles.

For me users problems in mailinglists are no suggestion to document the way
the software works, but they are a suggestion, that the software needs
improvement. There are long-standing problems which need lots of work (like
the still missing specific relation handlings) and others which only need
finetuning.

> 4. Add the basic help steps yourself as a start. It's a lot easier for 
> both sides (devs and users) to have a minimal help page to start to 
> work from. If questions arise and the dev tells the user: "Please have 
> a look at URL xy. It's not perfect, it's a wiki, please improve it" - 
> that's a lot more helpful than just: "do it yourself".

At least my experience shows this is not true. Since I'm developing JOSM I
tried multiple times. None of the stubs I wrote ever got expanded. Either
there is someone caring for documentation or there is not. This is not the
task of the developers, they are to valuable to continue development.

For me programming is like walking - very easy. I learned that this is
different for most other people and that only few people are really able to
do good programming. I wont allow that these few people are scared away
because they are forced to document their work more than necessary. 
Documentation is an independent task (not only for OpenSource, but also in
larger companies). If nobody wants to document JOSM, then we have no
documentation. As long as we try to improve the UI to be better
understandable whenever possible I have no problem with this.

> I guess just a little bit development could boost the user participation.

No. All my experience shows that this is untrue. People either help or they
don't help.

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


_______________________________________________
josm-dev mailing list
josm-dev at openstreetmap.org
http://lists.openstreetmap.org/listinfo/josm-dev