Rework of the JOSM Help page

[Klumbumbus]

I wanted to created this ticket already since some month. Since we just discuss #12800, I want to add this topic.
Although I appreciate your work to improve the wiki pages, in my opinion the Help page in version 143 before your edits was better than now.
Specific things I don't like with the current version 213:

• All the shortcuts. There are special pages where they are listed.
• Too special things for the starting help page. Actually the whole JOSM tools section should be removed in my opinion.
• One of the most important parts of the page (the names of the JOSM interface parts (main toolbar, toogle dialogd,...)) is condensed in an image description and you cannot even recognize the referred content of the picture.
• I miss the links to the main menu entries
• The whole page looks unstructured
• Non working links
• Missing verbs, e.g. there many ways to load existing data in JOSM

[openstreetmap.org-user-d1g]

Too special things for the starting help page. Actually the whole JOSM tools section should be removed in my opinion.

Not now, I reworked https://josm.openstreetmap.de/wiki/Introduction and started work on https://josm.openstreetmap.de/wiki/Help/Concepts/Object.

You should use these 2 newbie-only links.

Power users need documentation too.

IMO https://josm.openstreetmap.de/wiki/Help is perferct place to provide overview of tools and interface.

We shouldn't sacrifice tools or interface (I will re-add more recent interface materials, see below) in favour just one topic.

All the shortcuts. There are special pages where they are listed.

yes, but some of functions are not known by their names, but by hotkeys. Many of JOSM users speak naturally when helping each other: ​http://forum.openstreetmap.org/viewtopic.php?id=2714. I think it will be so forever, there no documentation would force users to use tool names over shortcuts or activation steps.

Simply read any IDE/CAD/GIS documentation, it is filled "do a, do b, do c" everywhere. If you drop it, it will be not useless but significantly harder to understand.

Personally, I have no problems with any text, as I can read source code; but not many users can really do this.

I miss the links to the main menu entries

We should add TOC to the left, so it is more reachable.

One of the most important parts of the page (the names of the JOSM interface parts (main toolbar, toogle dialogd,...)) is condensed in an image description and you cannot even recognize the referred content of the picture.

Yes, but big readable image will blow page (which is already 2 screens big with only frequently discussed tools); we should use text and diagrams (of pseudo interface).

I plan to add paragraph "JOSM interface overview" (similar to No3 in https://josm.openstreetmap.de/wiki/Help#JOSMinterface) but more desriptive

Main menu is even bolded here, but yes it is at the bottom of the page at least now.

Non working links

For example, is there still any? https://josm.openstreetmap.de/wiki/Help?version=213

The whole page looks unstructured

Not unstructured but long, list-like page;

Any list page will look "unstructured": ​https://en.wikipedia.org/wiki/List_of_lists_of_lists

I wasn't using syntax:

• Like
  • This
    • One

Because I don't know every single trick of tracwiki syntax. Feel free use this "structured" syntax instead of heading.

H3-H6 headings are good because you link to them directly. Table or list-based solutions are horrible in this sense.

Missing verbs

Yes, during merges and content moves I have difficulties to spot them (if they are not highlighted as mistakes), none of spellcheckers will help in this aspect.

[openstreetmap.org-user-d1g]

As with any wiki, I found bizarre syntax to create #anchors: ​https://trac.edgewall.org/wiki/WikiFormatting#SettingAnchors

jump
...

AAA: Jump not highlighed

skip
...

BBB: skip here should be highlighted

But again, I find H1-H6 as way easier to write/use/translate; in most cases you can re-organize content so you don't have to use anchor syntax.

Anchors in text often mean you need more perspectives (separate pages or paragraphs).

If anyone here teach me how to include/transclude pages or use temaplates at tracwiki, then I will spend some time on navigational templates at the bottom of pages.

One examples would be to create navigational template for main menu.

[Klumbumbus]

Replying to openstreetmap.org-user-d1g:

I miss the links to the main menu entries

We should add TOC to the left, so it is more reachable.

I mean this link list https://josm.openstreetmap.de/wiki/Help?version=143#MainMenu

One of the most important parts of the page (the names of the JOSM interface parts (main toolbar, toogle dialogd,...)) is condensed in an image description and you cannot even recognize the referred content of the picture.

Yes, but big readable image will blow page

I think it was fine in version 143

Non working links

For example, is there still any? https://josm.openstreetmap.de/wiki/Help?version=213

• Potlatch2 Vespucci
• [Help/Action/DisconnectNodeWay DisconnectNodeWay]
• [Help/Action/AddIntersections AddIntersections]
• Split geometry by selected line

[openstreetmap.org-user-d1g]

I think it was fine in version 143

Regarding size yes, but regarding labels... No, on your image there only 5 elements, when there more elements.

"Edit toolbar" is especially imprecise, when bottom half is only "pictograms of toggle dialogues" or "state of toggle dialogues".

Also, text was in your version text was in English, but I created using it using numbers, so it is easier to precieve. Therefore I recreated it, otherwise it was fine.

Main editing area/viewport is not shown in picture.

Main menu and status panel is without border. If we use borders, then contrast/ of original image should be lowered IMO.

Potlatch2? Vespucci?

[Help/Action/DisconnectNodeWay DisconnectNodeWay]
[Help/Action/AddIntersections AddIntersections]
Split geometry by selected line

They should be red links, but in tracwiki they just broke. Link syntax is correct, but destination page doesn't not exist (yet). Easiest solution is to create stub of the page with few words, not to remove this text.

Links lead to correct destinations IIRC.

​https://en.wikipedia.org/wiki/Wikipedia:Red_link: Red links for subjects that should have articles but do not, are not only acceptable, but needed in the articles. They serve as a clear indication of which articles are in need of creation, and encourage it. Do not remove red links

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

Replying to openstreetmap.org-user-d1g:

I miss the links to the main menu entries

We should add TOC to the left, so it is more reachable.

I mean this link list https://josm.openstreetmap.de/wiki/Help?version=143#MainMenu

First I moved https://josm.openstreetmap.de/wiki/Help?version=143#MainMenu to https://josm.openstreetmap.de/wiki/JOSM%20interface?version=4#MainMenu
But recently I created separage pages just for main menu:
https://josm.openstreetmap.de/wiki/Help/Menu

And this page linked BOTH at the top and at the bottom of these pages:
https://josm.openstreetmap.de/wiki/Help/Menu/File
https://josm.openstreetmap.de/wiki/Help/Menu/Edit
https://josm.openstreetmap.de/wiki/Help/Menu/View
https://josm.openstreetmap.de/wiki/Help/Menu/Tools
https://josm.openstreetmap.de/wiki/Help/Menu/Selection
https://josm.openstreetmap.de/wiki/Help/Menu/Presets
https://josm.openstreetmap.de/wiki/Help/Menu/Imagery
https://josm.openstreetmap.de/wiki/Help/Menu/Audio
https://josm.openstreetmap.de/wiki/Help/Menu/Help
https://josm.openstreetmap.de/wiki/Help/Menu/Data

Only at bottom (not sure if it was good idea):
https://josm.openstreetmap.de/wiki/Help/ToggleDialogs

Simply link to particular menu now; or extend https://josm.openstreetmap.de/wiki/Help/Menu if needed at all.

Main menu is not different from main menus of many other programs, there nothing to teach readers IMO. Collection of relevant links is all we need here.

[openstreetmap.org-user-d1g]

Probably it would be better to change naming convention to

https://josm.openstreetmap.de/wiki/Help/JOSM interface/File menu
https://josm.openstreetmap.de/wiki/Help/JOSM interface/Edit menu

So you can include everything:

https://josm.openstreetmap.de/wiki/Help/JOSM interface/ToggleDialogs
https://josm.openstreetmap.de/wiki/Help/JOSM interface/RelationEditor

But at tracwiki this is more error prone than on other wikis AFAIK.

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

• All the shortcuts. There are special pages where they are listed.

In version 55 shortcuts were listed as "Getting started" material (I completely agree with this)

They were present in version 109 too: https://josm.openstreetmap.de/wiki/Help?version=109

In version 129 "Getting started" section got too big for "5-10 minutes tutorial": https://josm.openstreetmap.de/wiki/Help?version=129

And it was slitted in "within this wiki" (offline help) and "other resources": https://josm.openstreetmap.de/wiki/Help?version=130

In version 133 help activation steps were covered https://josm.openstreetmap.de/wiki/Help?version=133 but this is unnecessary as if user managed to read this text... Then he pressed at least something to get there. There no documentation in the world^{*except JOSM} that tells you "enter www.org/documentation" at first line :)

Lastest version before my content moves: https://josm.openstreetmap.de/wiki/Help?version=143 is incomplete and imprecise in descriptions.

There no reason to create "HOWTO" or "FAQ" page. All FAQ questions should be covered at https://josm.openstreetmap.de/wiki/Help and more precise information should be covered at more complete pages.

Not only https://josm.openstreetmap.de/wiki/Help?version=216 directly covers "You first JOSM edit", "JOSM concepts", "JOSM interface", "JOSM tools by function" but it also provides links to plugins and menus only when really needed/necessary.

Simply listing all links "here all plugins" "all items from main menu" "here all styles" is not enough to present some concept for the first time. And by the way, it was done in https://josm.openstreetmap.de/wiki. Second frontpage with same content is overkill.

https://josm.openstreetmap.de/wiki/Help?version=216#JOSM you explain concept first without any links, then you add the most relevant links to bits of text. This way text be compact and deep (because of links you place);

One example from 143 https://josm.openstreetmap.de/wiki/Help?version=143 is that wrong statement that you NEED (Getting Started) to read all these long FAQ pages or all shortcuts or all broad external FAQ pages filled with un"popular" questions.

[openstreetmap.org-user-d1g]

When it comes to complex topics (tools, menus), they should be splitted at least two parts

• Essential tools and cocepts
• Complete reference

As we don't have "complete reference" of tools^{See JOSM interface}, https://josm.openstreetmap.de/wiki/Help#JOSMtools presents only non-duplicate tools (with strong preference to core tools):

https://josm.openstreetmap.de/wiki/Help#Basicshapeofobjects

"Basic shape of objects" was described in the way so we can finally see both New-York in OSM and next (name of unknown and unpopulated rural area).

https://josm.openstreetmap.de/wiki/Help#JOSMtools miss relation-centric tools, but I stated that any relation can be edited with Relation Editor

[openstreetmap.org-user-d1g]

When you finish "essential tools" parts, your perfect "Begginers guide to JOSM" is written or can be composed with links that cover one topic in brief detail and in-depth.

DO NOT bloat "essential parts" everywhere.
DO NOT remove "essential parts"^{JOSM Terminology start josm} or "noob version of this page" everywhere.

Before adding new content to some page (not wrong at all) you should follow it from front page^{this one}, if it was covered - stop; if it was covered too deep - make it more visible.

[Klumbumbus]

Replying to openstreetmap.org-user-d1g:

I think it was fine in version 143

Regarding size yes, but regarding labels... No, on your image there only 5 elements, when there more elements.

Yes there was room for improvement. However the point is that it was understandable at first view. Now it is nearly useless because the image is to small and you cannot see the numbers. Also the connectin between the numbers and the words is "difficult" because they are not listed among each other but side by side with line breaks.

(BTW it is not my image, I just edited it.)

They should be red links, but in tracwiki they just broke.

you can add wiki: at the beginning of the link

Missing verbs

My english is not perfect as well, however I see that you always forget the verb after the word "there" when it is necessary. I hope this helps you.

If some object can be represented with single node or way and multiple tags supported by software, then there is no need in relations. But there are some rare cases where it is theoretically and practically impossible to use relation (ex. turn restrictions, will be covered below).

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

Missing verbs

My english is not perfect as well, however I see that you always forget the verb after the word "there" when it is necessary. I hope this helps you.

If some object can be represented with single node or way and multiple tags supported by software, then there is no need in relations. But there are some rare cases where it is theoretically and practically impossible to use relation (ex. turn restrictions, will be covered below).

Yep, ​it's a verb; I forgot ​this English idiocy. As excuse I would say that most of the verbs in Russian constructed with prefixes/suffixes and it is possible to omit "be".

"Russians omit the verb "to be" (быть) in the present tense." - ​http://masterrussian.com/aa120199a.shtml and "Present tense endings of Russian verbs" ​http://masterrussian.com/aa021100a.shtml

Next time you see a person omitting verbs in the present tense would give you a hint of their native language categories :-)

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

• One of the most important parts of the page (the names of the JOSM interface parts (main toolbar, toogle dialogd,...)) is condensed in an image description and you cannot even recognize the referred content of the picture.
• I miss the links to the main menu entries

I re-created overview using ascii art, so it is independent of images Help#JOSMinterfaceoverview

Any readable image or diagram will be bigger than this text IMO.

PS. I also bolded main menu, modes and windows (this is how toggledialogs named in the main menu).

[bastiK]

I also think the changes by d1g need further improvement:

• Some sentences appear as personal opinion, slight criticism or hints/suggestions towards the developers. Whether it is intended or not, I don't think the help portal is the right place for JOSM bashing. Examples:
  • "Unlike osm.org, most other editors and software, you have to hold right mouse click to navigate"
  • "Some of the default hotkeys may surprise editors from simple editors" - Also offensive towards supposedly "simple" editors
  • "some of the settings are not accessible via settings menu or just spread everywhere in the editor" - overstatement (?), in any way more intimidating than helpful
  • "Starting screen may be confusing for newcomers" - instead of this statement, explain it to avoid supposed confusion
  • "Pay attention, that menus in JOSM are very deep, just couple of examples below" - I don't think that JOSM menus are overly deep compared to other software of similar complexity. Right-click menu is a normal concept. The list of examples seem twisted to make a point.
• ASCII art for user documentation is not appropriate. The image from version 143 is way better.
• Icons should be added if available as seen in "Other dialogs", version 143.
• No Shortcuts on the main help page
• No reference to UtilsPlugin2 features on the main help page, maybe except in a separate section
• "Spline or Bezier from commandline" - what does this mean?

[openstreetmap.org-user-d1g]

Replying to bastiK:

I also think the changes by d1g need further improvement:

• Some sentences appear as personal opinion, slight criticism or hints/suggestions towards the developers. Whether it is intended or not, I don't think the help portal is the right place for JOSM bashing. Examples:
  • "Unlike osm.org, most other editors and software, you have to hold right mouse click to navigate"

Where is bashing here? JOSM navigation is different from other tools users will encounter. This is not going to change because how code is organized.

• "Some of the default hotkeys may surprise editors from simple editors" - Also offensive towards supposedly "simple" editors

I don't see how this is offensive; feel free to reword, I don't see how different shortcuts schemes could be explained for the first time.

After I wrote this sentence, I created https://josm.openstreetmap.de/wiki/iD#Shortcuts to explain this topic in detail; no "nice" or "offensive" sentences would help readers. Now this resource linked closer to the beginning of the page "Migration assist from ...".

Tried to reword without "other editors".

• "some of the settings are not accessible via settings menu or just spread everywhere in the editor" - overstatement (?), in any way more intimidating than helpful

This text ATM contains one link, but it should link to two resources:
https://josm.openstreetmap.de/wiki/Help/Preferences/Advanced#Explanation
https://josm.openstreetmap.de/wiki/Help/JOSM%20interface%20customization
https://josm.openstreetmap.de/wiki/Help/Dialog/LayerList#Layertypes - these menus are overlooked if they weren't translated or discussed.

There at least 9 activation steps without any menus and 20+ settings only available via advanced settings.

• "Starting screen may be confusing for newcomers" - instead of this statement, explain it to avoid supposed confusion

Simplified.

• "Pay attention, that menus in JOSM are very deep, just couple of examples below" - I don't think that JOSM menus are overly deep compared to other software of similar complexity. Right-click menu is a normal concept. The list of examples seem twisted to make a point.

There many panels and items with right click actions, they are explained very deep at wiki and they have just a few translations. There no simple way to study menus than to follow deeply nested links or to know beforehand where all menus are.

Over-promoting them, until they get good translations wouldn't harm this page IMO. [These statements almost at the bottom of the page](https://josm.openstreetmap.de/wiki/Help?version=254#JOSMinterfacecompletereference).

Also, I don't have good ideas what should be written in "JOSM interface" page. Probably a complete list of all right-click menus and all dialogues would make sense (it wasn't covered anywhere before). This could be done at wiki/Help page, but I'm not sure how long complete list would be, so created a separate page first.

https://josm.openstreetmap.de/wiki/Help/Menu/File - is 3 levels deep any other menu is just worse than this.

• ASCII art for user documentation is not appropriate. The image from version 143 is way better.

Ii was used before me. https://josm.openstreetmap.de/wiki/Help/Action/SplitWay - this was present since 2007: https://josm.openstreetmap.de/wiki/Help/Action/SplitWay?version=6 and probably in the other places

Image from 143 is dated or contains contradictional terminology:

• "Windows" in the main menu, but "Toggle dialogues"
• "Modes" are not represented
• bottom of the "Edit toolbar" is just states for windows - this wasn't covered anywhere before. But instead, it was repeated at the top of every significant window:

https://josm.openstreetmap.de/wiki/Help/Dialog/LayerList#ShowingandHidingtheLayerListDialogWindow
https://josm.openstreetmap.de/wiki/Help/Dialog/TagsMembership "If it is not displayed then:"

I de-duplicated repetitions and moved them to the main page, where they should be.

https://josm.openstreetmap.de/wiki/Help?version=143#JOSMinterface

"Depending on which plugins you have installed you may have more options on this menu" moved to main menu page, because old text explained almost nothing:

https://josm.openstreetmap.de/wiki/Help/Menu

• Icons should be added if available as seen in "Other dialogs", version 143.

It will take additional time to add them.

• No Shortcuts on the main help page

Any reason for this? As I said before, activations steps (menu names, shortcuts) are often used instead of names in complex software. JOSM is not exception to this.

Different style^could be used to distinguish them from the main text, but I don't have good ideas.

• No reference to UtilsPlugin2 features on the main help page, maybe except in a separate section

[Selection tools from UtilsPlugin2 were linked under "Selection tools" section](https://josm.openstreetmap.de/wiki/Help?version=254#Selection). How "new section" should be titled?

UtilsPlugin2 is a frequently recommended plug-in, reason not to present it?

• "Spline or Bezier from commandline" - what does this mean?

Commands from commandline plugin.

​http://wiki.openstreetmap.org/wiki/JOSM/Plugins/CommandLine

[openstreetmap.org-user-d1g]

Continued simplification,

https://josm.openstreetmap.de/wiki/Help?version=259#JOSMinterfaceoverview - pseudo-graphic replaced with more recent image; probably other links can be added; but layout is complex here
https://josm.openstreetmap.de/wiki/Help?version=255#JOSMstartingscreen - images eaten space in "interface" but they were partially covered in Introduction after they were put first time; text and link to Introduction will be enough.

[bastiK]

Replying to openstreetmap.org-user-d1g:

Replying to bastiK:

I also think the changes by d1g need further improvement:

• Some sentences appear as personal opinion, slight criticism or hints/suggestions towards the developers. Whether it is intended or not, I don't think the help portal is the right place for JOSM bashing. Examples:
  • "Unlike osm.org, most other editors and software, you have to hold right mouse click to navigate"

Where is bashing here? JOSM navigation is different from other tools users will encounter. This is not going to change because how code is organized.

I've changed the sentence.

• "Some of the default hotkeys may surprise editors from simple editors" - Also offensive towards supposedly "simple" editors

I don't see how this is offensive; feel free to reword, I don't see how different shortcuts schemes could be explained for the first time.

Okay, but I don't really like how the "Concepts" section looks now. A changeset is part of the OSM data model. Then the bullet points "shortcuts", "Preferences" and "Undo/Redo" - it feels a bit strange to put them at this prominent place.

After all, these are "concepts", that most new users should be more or less familiar already from other software and it is not that much different in JOSM. The finer points can be learned later, it doesn't have to be the first thing.

• "some of the settings are not accessible via settings menu or just spread everywhere in the editor" -

[...]

Don't you get how this sentence is can be seen as negative criticism? If even the authors of the help pages (= developers?) think the software is rubbish, why should a new user be bothered to learn and use it?

There at least 9 activation steps without any menus

??

and 20+ settings only available via advanced settings.

Probably more like 200+. The advanced settings are called "advanced" for a reason. The normal user should have no reason to change anything there.

Also, I don't have good ideas what should be written in "JOSM interface" page. Probably a complete list of all right-click menus and all dialogues would make sense (it wasn't covered anywhere before). This could be done at wiki/Help page, but I'm not sure how long complete list would be, so created a separate page first.

Okay...

• ASCII art for user documentation is not appropriate. The image from version 143 is way better.

Ii was used before me. https://josm.openstreetmap.de/wiki/Help/Action/SplitWay - this was present since 2007: https://josm.openstreetmap.de/wiki/Help/Action/SplitWay?version=6 and probably in the other places

Sure, ASCII may be better than nothing. But it is not good to replace an existing image on one of the main pages by text.

• No Shortcuts on the main help page

Any reason for this? As I said before, activations steps (menu names, shortcuts) are often used instead of names in complex software. JOSM is not exception to this.

Its a matter of style and main target audience. This page is an entry-point and and landing place for newcomers. It shouldn't be stuffed with technical information.

• No reference to UtilsPlugin2 features on the main help page, maybe except in a separate section

[Selection tools from UtilsPlugin2 were linked under "Selection tools" section](https://josm.openstreetmap.de/wiki/Help?version=254#Selection). How "new section" should be titled?

UtilsPlugin2 is a frequently recommended plug-in, reason not to present it?

Because this page documents the main program. You can create a page "popular plugins" or something like that and link to the page.

• "Spline or Bezier from commandline" - what does this mean?

Commands from commandline plugin.

​http://wiki.openstreetmap.org/wiki/JOSM/Plugins/CommandLine

Very unhelpful - misleading and without and context or further information.

Replying to openstreetmap.org-user-d1g:

Continued simplification,

https://josm.openstreetmap.de/wiki/Help?version=259#JOSMinterfaceoverview - pseudo-graphic replaced with more recent image; probably other links can be added; but layout is complex here

Looks much better!

[openstreetmap.org-user-d1g]

Replying to bastiK:

Okay, but I don't really like how the "Concepts" section looks now. A changeset is part of the OSM data model. Then the bullet points "shortcuts", "Preferences" and "Undo/Redo" - it feels a bit strange to put them at this prominent place.

Changesets doesn't belong to OSM data model section either. OSM model is complete without changesets. Similarly how changesets discussions are not included or notes. Created separate heading.

After all, these are "concepts", that most new users should be more or less familiar already from other software and it is not that much different in JOSM. The finer points can be learned later, it doesn't have to be the first thing.

Preferences are absolutely unique per each application. https://josm.openstreetmap.de/wiki/Help/Preferences
Hotkeys are absolutely unique per each application. https://josm.openstreetmap.de/wiki/Shortcuts
Command Stack (visual undo) is only present in JOSM https://josm.openstreetmap.de/wiki/Help/Dialog/CommandStack

If you think they are unnecessary - go ahead and remove them.

• "some of the settings are not accessible via settings menu or just spread everywhere in the editor" -

[...]

Don't you get how this sentence is can be seen as negative criticism? If even the authors of the help pages (= developers?) think the software is rubbish, why should a new user be bothered to learn and use it?

Only you said "rubbish". Quoted text says that they are spread in editor. Quoted text says only some of them not accessible via settings menus.

There at least 9 activation steps without any menus

??

"Pin" icons and now "gears" are spread everywhere in windows ("eyes" in layers). This is not part of any system. If you think they are intuitive, you are wrong.

and 20+ settings only available via advanced settings.

Probably more like 200+. The advanced settings are called "advanced" for a reason. The normal user should have no reason to change anything there.

From https://josm.openstreetmap.de/wiki/Help#preferences:

Preferences (complete reference) - some of the settings are not accessible via settings menu or just spread everywhere in the editor

Yes, so what's wrong with text?

• ASCII art for user documentation is not appropriate. The image from version 143 is way better.

Ii was used before me. https://josm.openstreetmap.de/wiki/Help/Action/SplitWay - this was present since 2007: https://josm.openstreetmap.de/wiki/Help/Action/SplitWay?version=6 and probably in the other places

Sure, ASCII may be better than nothing. But it is not good to replace an existing image on one of the main pages by text.

I'm not going to repeat mistakes and imprecise text I found and fixed (2 times already) in this "existing picture".

• No Shortcuts on the main help page

Any reason for this? As I said before, activations steps (menu names, shortcuts) are often used instead of names in complex software. JOSM is not exception to this.

Its a matter of style and main target audience. This page is an entry-point and and landing place for newcomers. It shouldn't be stuffed with technical information.

What is "technical information"? A shortcut? A menu name? A icon?

Tracwiki is terrible at multiple perspectives. How do you suggest to solve "matter of style and main target audience"?

• No reference to UtilsPlugin2 features on the main help page, maybe except in a separate section

[Selection tools from UtilsPlugin2 were linked under "Selection tools" section](https://josm.openstreetmap.de/wiki/Help?version=254#Selection). How "new section" should be titled?

UtilsPlugin2 is a frequently recommended plug-in, reason not to present it?

Because this page documents the main program. You can create a page "popular plugins" or something like that and link to the page.

Then what should be left at wiki/Help? List of the default tools nobody request or doesn't have questions about?

Good you meantion plugin name, because it should be included in core, partially or fully, several tickets I was able to find: #8864, #8821 - I'm sure there were others

• "Spline or Bezier from commandline" - what does this mean?

Commands from commandline plugin.

​http://wiki.openstreetmap.org/wiki/JOSM/Plugins/CommandLine

Very unhelpful - misleading and without and context or further information.

No. You forgot to quote context, I will help:
https://josm.openstreetmap.de/wiki/Help
https://josm.openstreetmap.de/wiki/Help#JOSMtoolsincompletereference
https://josm.openstreetmap.de/wiki/Help#Basicshapeofobjects

Spline or Bezier from commandline is not linked because nobody wrote an article about it at this wiki.

And even resource created by it's author (Hind) isn't good:
​http://wiki.openstreetmap.org/wiki/JOSM/Plugins/CommandLine#Usage (Russian version is better, but lacks demontrations)

Replying to openstreetmap.org-user-d1g:

Continued simplification,

https://josm.openstreetmap.de/wiki/Help?version=259#JOSMinterfaceoverview - pseudo-graphic replaced with more recent image; probably other links can be added; but layout is complex here

Looks much better!

Of course it does, it took 20 minutes to create it, instead of 2 mins for text.

[openstreetmap.org-user-d1g]

Replying to bastiK:

• No Shortcuts on the main help page

Any reason for this? As I said before, activations steps (menu names, shortcuts) are often used instead of names in complex software. JOSM is not exception to this.

Its a matter of style and main target audience. This page is an entry-point and and landing place for newcomers. It shouldn't be stuffed with technical information.

How many "Newcomer" pages you intended to create and maintain?

https://josm.openstreetmap.de/wiki/Introduction - this is the only Introduction page.

1. it is linked from JOSM editor start screen: https://josm.openstreetmap.de/wiki/StartupPageSource#GettingStarted
2. it is linked from main JOSM page: https://josm.openstreetmap.de/wiki#GettingStartedHelp
3. it is linked as very first link at wiki/Help: https://josm.openstreetmap.de/wiki/Help#YourfirsteditswithJOSM

Yes, newcomers can use Help page along with other users of JOSM.

Shortcuts were visible at main page since the beginning, I don't see reason not to include them directly at the page: https://josm.openstreetmap.de/ticket/12801?#comment:7

Furthermore, if this page gets outdated in other languages, users are still able to read pictures along with basic English instructions. Mentioning keys will help to recognize tool equally with icons or menu names.

In addition to this, some users do not use "Main menu" at all (for many reasons). I don't know why you want to remove the only way to recognize tool for them.

[openstreetmap.org-user-d1g]

Replying to bastiK:

Because this page documents the main program. You can create a page "popular plugins" or something like that and link to the page.

"All plugins" were documented already, there no need to do this again: https://josm.openstreetmap.de/wiki/Plugins

Furthermore, "popular plug-ins" was removed just 10 days ago. Personally I don't see any good reason for it.

What is the "main" program? If WMS plugin was included in core 4 years ago, makes it "main" program now? If building_tools is not included in main program because it contains bugs (if used against intended usage) and rare stability issues, but everyone uses or recommends it, we should create separate page where it will be listed along with other non "main" tools?

https://josm.openstreetmap.de/ticket/7328?cversion=0&cnum_hist=33#comment:5

https://josm.openstreetmap.de/wiki/Help "JOSM tools" section does what it does: it describes individual tools, not plug-ins. And if tool was from plugin, it explicitly says "from (plugin name)".

Simply repeating all menus and menu items (which user already seen in JOSM) doesn't help to learn tools https://josm.openstreetmap.de/wiki/Help?version=143#JOSMinterface

If user had problems with interface and captions in JOSM, then by copying very same help instructions you only waste everybody time (since we need to translate it and to update it over time).

[openstreetmap.org-user-d1g]

Actually the whole JOSM tools section should be removed in my opinion.

Reasons why Help#Rotation was created were covered in #12800, comment 39

Similar sections created using roughly the same approach.

There are many tools I personally don't like at Help, but if they are discussed, they are subject to inclusion in Help#JOSMtoolsincompletereference.

[openstreetmap.org-user-d1g]

Deletion tools are not present at Help because nobody discussed them!

So either:

1. there nothing to discuss
2. they are not complex

Result: no section Help#Deletion.

[andygol]

It would be great if Help page have been reverted to its previous state (before d1g modifications).

Now it is overloaded with unnecessary details and looks quite messy.

/cc Klumbumbus, bastiK, stoecker, Don-vip

[openstreetmap.org-user-d1g]

Okay, but please keep history.

To me, there almost no information in version=143, 60% of the page is a copy of JOSM interface.

JOSM interface is now linked everywhere (e.g. at Help/StatusBar)

JOSM interface was overpresented IMO; see "QGIS GUI" section at ​http://docs.qgis.org/2.14/en/docs/user_manual/

"General Tools" is absolutely absent in version 143 - I tried to mention tools, but they become bloated at some point.

[openstreetmap.org-user-d1g]

I would move page Help/StatusBar to Help/JOSM interface/StatusBar but this is tedious process at tracwiki and many links would be broken (left without automatic redirect).

[openstreetmap.org-user-d1g]

Great advantage of ​http://docs.qgis.org/2.14/en/docs/user_manual/introduction/qgis_gui.html over https://josm.openstreetmap.de/wiki/Help?version=143#JOSMinterface is that you only need one big page "qgis_gui.html", not multiple (Help/Menu/Selection, Help/Menu/Tools, ...)

Sub pages are fine, but they require clicking before you reach actual information.

[bastiK]

Tomorrow I will revert Help to version 143 (history is preserved). The intention being that parts of the improvements made in the meantime can be integrated by other wiki-editors later on.

The portals project is not on a path where it will be adopted as front page or main help page by the JOSM team. To avoid redundancy in the documentation, I would like to put an end to it. I will delete all wiki pages related to portals. openstreetmap.org-user-d1g, sorry about that! Please create a backup of these pages if you like to save your work!

Edit: See #12800:45 for a backup of PortalTiles?version=14.

[openstreetmap.org-user-d1g]

Replying to bastiK:

I will delete all wiki pages related to portals

Can you please name them?

To avoid redundancy in the documentation

Tools are not explained in 143, there no replacement for what I stated (Help/JOSM tools)

I understand this, but it will make exploration more difficult (more clicks because all information in sub pages).

Personally I won't use help portal if there no JOSM tools. Because I explain JOSM in tools 90% of the time and 10% of the time is a first time screen with all menus.

I watched many videos from CAD/QGIS tutors; I was a CAD user/developer for a couple of years. I used to teach CAD other in the past; most of their materials are about tools while interface covered as reference (like in QGIS documentation)

In order to present materials from 2 perspectives (interface and tools) you may create some duplication.

I would keep both perspectives, but if nobody wants it here, I don't mind.

[bastiK]

Replying to openstreetmap.org-user-d1g:

Replying to bastiK:

I will delete all wiki pages related to portals

Can you please name them?

That would be:

• Portals
• PortalTiles
• JOSM channels
• JOSM Extensions and installation steps
• Extend JOSM - I don't like how it gives bits and pieces from different topics. It should suffice to link to the corresponding page, with possibly one phrase to give an idea what the terms mean.
• About JOSM - The only unique content is currently the list of contributors. I'll move it back to DevelopersGuide, although this might not be the ideal place either.

Not related to portals, but I will also delete:

• Help/Downloading data - don't see the significance of such a list / table
• JOSM interface - Will probably not be needed after rollback of Help

To avoid redundancy in the documentation

Tools are not explained in 143, there no replacement for what I stated (Help/JOSM tools)

In order to present materials from 2 perspectives (interface and tools) you may create some duplication.

I would keep both perspectives, but if nobody wants it here, I don't mind.

In JOSM, there is a close connection between menu items (i.e. interface) and tools. Let's keep Help/JOSM tools for now.

Other pages that need significant rework:

• Help/JOSM interface customization
• Help/Relations

[openstreetmap.org-user-d1g]

JOSM Extensions and installation steps
JOSM channels
PortalTiles

True, we agreed on this.

Portals

Let's kill this one too, why not; but it was linked from "important" (portal like) pages.

Help/Downloading data - don't see the significance of such a list / table

Is there single place at https://josm.openstreetmap.de/ that describes all possibilities to load data in JOSM?

I don't mind to move this table somewhere.

Extend JOSM - I don't like how it gives bits and pieces from different topics. It should suffice to link to the corresponding page (Help/Styles/MapCSSImplementation), with possibly one phrase to give an idea what the terms mean.

I don't like it too, but duplication is here to avoid translation of absolutely massive pages e.g. Help/Styles/MapCSSImplementation

I can translate "headings" or one-liners at Extend JOSM#Customstylesandpublication but it will be 20x work to translate complete page.

I would happy to see if somebody would translate Extend JOSM is their language.

IMO it is worse to copypaste MapCSSImplementation in other language and translate only headings because now you have to sync body of the article.

Intent was not to create collection of links or useless duplication, but aid quick translation (less content for minor languages with few editors).

Help/Relations

Same about Help/Validator. Is there any specific suggestions about content? Feel free to suggest further work using "outdated=" param as we did everywhere.

[openstreetmap.org-user-d1g]

Then what should we do about https://josm.openstreetmap.de/wiki/Help?version=143 if there no information about tools at this page?

Last time I said it in 12801#comment:23

[bastiK]

Replying to openstreetmap.org-user-d1g:

Let's kill this one too, why not;

I realize you spend a lot of time creating content for the wiki and are passionate about it. Same is true for other team members. Unfortunately, there is no way to make everyone happy.

Extend JOSM - I don't like how it gives bits and pieces from different topics. It should suffice to link to the corresponding page (Help/Styles/MapCSSImplementation), with possibly one phrase to give an idea what the terms mean.

I don't like it too, but duplication is here to avoid translation of absolutely massive pages e.g. Help/Styles/MapCSSImplementation
[...]
Intent was not to create collection of links or useless duplication, but aid quick translation (less content for minor languages with few editors).

I understand your argument, but disagree that the page was a solution to the mentioned translation issues.

Then what should we do about https://josm.openstreetmap.de/wiki/Help?version=143 if there no information about tools at this page?

Other wiki editors may integrate this information as they see fit.

[openstreetmap.org-user-d1g]

Replying to bastiK:

Let's kill this one too, why not;

I realize you spend a lot of time creating content for the wiki and are passionate about it. Same is true for other team members.

Well my "Let's kill this one too, why not;" wasn't passive-aggressive. You ommited the most important part about "but it was linked from "important" (portal like) pages" - e.g. second word in Changelog is now "broken" link to "portals".

Unfortunately, there is no way to make everyone happy.

There is. See my point about duplication and 2 (and more than) perspectives. #comment:1 #comment:27 #comment:28

CAD software is the most complex tools you will/may encounter in your life, yet they allow duplication.

They duplicate tools in 1. workflows 2. UI lists 3. tool descriptions 4. overview tool guides 5. limited duplication in first time guides 6. rarely in comparisons

It saves so much of my time to have tools explained everywhere.

In JOSM, there is a close connection between menu items (i.e. interface) and tools.

Interface can be skipped if/when you know all of the Shortcuts; especially when you disable interface on purpose

I understand your argument, but disagree that the page was a solution to the mentioned translation issues.

I think we should create a Glossary page to include "all important pages" once.

If some topic wouldn't be expanded, we can cover it at Glossary - what do you think?

I don't know what to say more about Help/Validator, but we have content at 4 pages and want to glue them together, so that readers follow all materials.

[Klumbumbus]

Help/Modes should be integrated into Help/EditToolbar and deleted too, imo.

[Klumbumbus]

Replying to openstreetmap.org-user-d1g:

"but it was linked from "important" (portal like) pages" - e.g. second word in Changelog is now "broken" link to "portals".

I changed or deleted the broken links.

[bastiK]

Klumbumbus: thanks, please go ahead!

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

Help/Modes should be integrated into Help/EditToolbar and deleted too, imo.

Yes, modes page was tiny.

Thanks to everyone for helping me and for providing additional external feedback!

1. I don't know how to fix Help/Relations for now. Images are just huge, one possibility is to slice them in 3 parts.
2. any other questions left unanswered to me? Can we close issue now?