> 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 :-) Sure. I today dig into the documentation stuff because I wanted to understand how it works. So, two samples from todays experiments http://josm.openstreetmap.de/wiki/Help/Dialog/History http://josm.openstreetmap.de/wiki/Help/Action/UploadSelection (here the documentation is ahead of the code - code to follow really soon ;-))
The context sensitive help in JOSM requires some clean up, too. For instance, currently it works in the JOSM main window only, not in modal dialogs, not in detached toggle dialogs, not in the history browser, etc. Today, I've fixed this too. And we also need some "meta-documentation" i.e. a short text explaining the how the help system works and what the structure of the online help looks like (there are pages for "Actions", pages for "Menues", pages for "Dialogs", etc.). -- Karl -----Ursprüngliche Nachricht----- Von: josm-dev-boun...@openstreetmap.org [mailto:josm-dev-boun...@openstreetmap.org] Im Auftrag von Ulf Lamping Gesendet: Sonntag, 4. Oktober 2009 23:54 An: josm-dev@openstreetmap.org Betreff: Re: [josm-dev] Please invest some time into documentation - especially confilict resolution 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 _______________________________________________ josm-dev mailing list josm-dev@openstreetmap.org http://lists.openstreetmap.org/listinfo/josm-dev _______________________________________________ josm-dev mailing list josm-dev@openstreetmap.org http://lists.openstreetmap.org/listinfo/josm-dev
