Modify

Opened 21 months ago

Last modified 12 months ago

#17927 new enhancement

Rollback Introduction page to ver 65

Reported by: andygol Owned by: team
Priority: normal Milestone:
Component: Wiki content Version:
Keywords: Help, Introduction Cc: Klumbumbus, Don-vip, Skyper, DiGro, leni

Description

It is proposed to move Introduction page back to version 65 and discard all edits made by openstreetmap.org-user-d1g

https://josm.openstreetmap.de/wiki/Introduction?version=65

Now this page does not perform its function of providing background information on how to work with JOSM. The page contains copy-paste information from Mapbox manual pages on how to edit OSM. Links to these guides can be placed at the end of the page.

Attachments (0)

Change History (11)

comment:1 Changed 20 months ago by andygol

Cc: Don-vip Skyper added

comment:2 Changed 14 months ago by skyper

Not sure if a roleback is the best as it is already translated and was changed afterwards plus there are more pages involved. Nevertheless, I also have some problems with certain wiki pages. In the mean time, I changed some but e.g. wiki:/Help/Action/Upload, wiki:/Help/Dialog/SelectionList or wiki:Help/Concepts/Object and more need some attention.

comment:3 Changed 14 months ago by Hb---

Does a sample page for JOSM Help content exists?

Do we have a sample formatting to display JOSM error messages?

Language dependent graphics should be avoided because they hinder translation. Please see https://josm.openstreetmap.de/wiki/Help/Action/JoinAreas?action=diff&version=16

comment:4 in reply to:  3 ; Changed 14 months ago by skyper

Cc: DiGro leni added

Replying to Hb---:

Language dependent graphics should be avoided because they hinder translation. Please see https://josm.openstreetmap.de/wiki/Help/Action/JoinAreas?action=diff&version=16

Screenshots are always language dependent. I understand, that the message should be written in text form but you can still place the screenshots on the right hand side.

The regularly updated language are Dutch and French and both translators do not seem to have problems with the screenshot.

comment:5 in reply to:  4 Changed 14 months ago by leni

I agree with skyper: most of the time, I don't have problems with screenshots (only with gifs, but they are understandable).
see page https://josm.openstreetmap.de/wiki/Fr%3AHelp/Action/SplitWay and I don't understand why the ones on the page https://josm.openstreetmap.de/wiki/Help/Action/JoinAreas?action=diff&version=16 have been removed.

comment:6 in reply to:  4 ; Changed 14 months ago by Hb---

Replying to skyper:

The beef on the Join Areas help page is the animated GIF which shows the actions benefit. The more content we place above this GIF the lower its visibility gets. Why should a help page start with error messages?

A typical help context page could be:


Menu Group > Menu Item as title of the page

"Icon-Symbol" Shortcut: Combi+Keystroke

Mouseover text from menu item

Descriptive text what the results of this action are and how to use it. Two to four sentences with an optimum of eight words. No sentences with relative clauses. Do's, no might be done's, no error messages and no Do not do's.

  • Optionally a step by step guide with bullet points or numbers.

"One static image or an animated GIF that
fits into the built in Help Browser
window. Optimal is language independency
and a size of around 480 x 480 pixel. Please
see https://josm.openstreetmap.de/wiki/Help
for an example image."

Below the first usage description more detailed hints and error messages are fine. Avoid any content from other dialogs here. (See outside of sample help page).

See also
List of related actions and topics

Back to Menu Group
Back to Main Help


END of typical help page

Help content needs to be short and bound to the action or dialog. Duplicate content in context sensitive help pages needs to be avoided. This mistake is currently made on the [Help/Action/CombineWay] page. Everything dealing with the Tags/Memberships Conflict Dialog should be moved to an own page. This new page needs to be the target for the help button in that dialog. See a good example in [Help/Dialog/EditValue] for a help page for a dialog.

JOSM can provide help content related to what the users sees. Help pages overloaded with content from other topics and from error messages hinder this idea. If needed, then error messages can have their own help pages, see https://josm.openstreetmap.de/wiki/DevelopersGuide/HelpSystem/HelpTopicsList

You wrote:

can still place the screenshots on the right hand side.

Theoretically yes, if the built in Help Browser would allow to place images. Currently not even the icon-symbol is shown.

comment:7 Changed 14 months ago by skyper

So we are in a pity. Is the wiki intended as wiki with nice images or as help content for the internal help browser? Note, the help browser displays everything inline at the moment, therefor I moved some [[PageOutline]] down already.

Do we need a wiki page for every action? Context sensible help supports anchors, so, no need for own pages. By the way, the bigger problem are the missing sensible help links in code, see #18651.
Where should messages be explained?

Yes, Tags/Membership Conflict Dialog could have an own page but it is not needed.

I understand your critics about the missing texts and the too prominent images on Help/Action/CombineWay. Gonna add some more text. Help/Dialog/EditValue is not a good example, though, as:

  • it is a page which will never have much content as the dialog is quite simple.
  • comparing an action and a dialog or panel is not good.
  • the messages when replacing/overwritting tags are missing.

I would place the screenshot on the right, too.

Gifs usually only show one selection and/or one use case, e.g. for Help/Action/JoinAreas this is only one example. So describing in text is better, like the messages.

There will always be exceptions and we need probably two or three different styles for actions, panels and additional help pages but some guidelines for structure and content would be nice.

To come back to the topic of this ticket, in general, linking instead of copying and respecting others' work should be two rules. Therefor copying the context from one external page to the wiki like on Introduction and other pages is not the way to go, and if you think the messages are too prominent why not simply move them down in a subparagraph instead of deleting the links like in Help/Action/JoinAreas.

comment:8 in reply to:  7 Changed 14 months ago by Hb---

Replying to skyper:

Is the wiki intended as wiki with nice images or as help content for the internal help browser?

Both! The current structure allows sharp focused context pages and very general pages like Rules or Introduction. But I doubt that JOSMs target audience needs 'nice' images.

therefor I moved some [[PageOutline]] down already.

As context specific pages should have one topic only, then a Table of Content is disturbing. It is not needed to promote the See also section at the top of the page.

... Context sensible help supports anchors, so, no need for own pages.

Complete context sensitivity means that each help button from each dialog leads to another help topic. The Conflicting Tags dialog is secondary and may arise on Help/Action/MergeNodes, Help/Action/CombineWay and Help/Action/JoinAreas. So a separate Help topic would be fine. So your feature request #18651 warms my heart.

Where should messages be explained?

Far below the usage description and below the description of advanced preferences for the tool.

Help/Dialog/EditValue is not a good example, though, as:

Yes. I grabbed it on first sight.

There will always be exceptions and we need probably two or three different styles for actions, panels and additional help pages

All default actions have keyboard shortcuts. Noting them near the top of the page gives good guidance. Crap, panels can have shortcuts too.

but some guidelines for structure and content would be nice.

Yes, some pages deteriorated a lot over time.

To come back to the topic of this ticket, in general, linking instead of copying and respecting others' work should be two rules. Therefor copying the context from one external page to the wiki like on Introduction and other pages is not the way to go,

Please see the German introduction. It invites to got the 5 steps from Newbie to active uploader.

and if you think the messages are too prominent why not simply move them down in a subparagraph instead of deleting the links like in Help/Action/JoinAreas.

Will do.

Last edited 14 months ago by Hb--- (previous) (diff)

comment:9 in reply to:  6 ; Changed 12 months ago by skyper

Replying to Hb---:

Replying to skyper:

can still place the screenshots on the right hand side.

Theoretically yes, if the built in Help Browser would allow to place images. Currently not even the icon-symbol is shown.

I tried to work around this with tables but failed:

  • #!rst: Did not find an option to disable borders.
  • #!table, #!th: Did not find a way to align text to top of cell.

Any hints?

Last edited 12 months ago by skyper (previous) (diff)

comment:10 in reply to:  9 Changed 12 months ago by skyper

Replying to skyper:

I tried to work around this with tables but failed:

  • #!rst: Did not find an option to disable borders.
  • #!table, #!th, #!td: Did not find a way to align text to top of cell.

Any hints?

Oh, it looks like #!td style="vertical-align: top" should do the job. Will retry these days.

comment:11 Changed 12 months ago by skyper

Ok, looks promising, only need to find out how to set the width of a column.

If there is any difference in relation membership or role, JOSM presents following warning and ask for confirmation

The warning lists each involved relation with its name, the number of members and if it is not complete downloaded in brackets and offers two options to hide this warning in future. Choosing "No" will cancel the whole action.

confirmation relation warning screenshot

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The owner will remain team.
as The resolution will be set.
to The owner will be changed from team to the specified user.
The owner will change to andygol
as duplicate The resolution will be set to duplicate.The specified ticket will be cross-referenced with this ticket
The owner will be changed from team to anonymous.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.