Rework of the JOSM wiki start page

[stoecker]

Hi,

It's fine that you try to improve the wiki pages of JOSM, but a major rework of the JOSM start page is something which no single individual is free to do without consensus. That design is based on the efforts of many contributors and changes of such amount should be discussed.

You try to fit everything into that page, but that's not necessary. It's a start page for a wiki site which has a proper working search engine. Not everything must be linked there.

And your tabular design simply was ugly. I reverted to the state before these changes.

[openstreetmap.org-user-d1g]

Hello! Yep, this topic is quite big.

but a major rework of the JOSM start page is something which no single individual is free to do without consensus

Sure thing, if anyone have better ideas or why this shouldn't be done - I'm listening.

For example, ​http://hudson-ci.org/ uses:

"First impression", "Use", "Extend". I experimented with "communicate" column (No 4), but it should be adjusted in some more clever way or simply described outside table.

It's a start page for a wiki site which has a proper working search engine.

Yes, butIMO users shouldn't be forced to used it every time, or click 2-5 links before they reach one of demanded resources.

And your tabular design simply was ugly

Yes, this is because of wordy sentence like ("Use one of 6 options above, more detailed instructions or learn about download options")

We can use CSS "width" or place hardcoded [ br ] everywhere; I will be absolutely okay with any solution.

You try to fit everything into that page, but that's not necessary.

Yes, I added more developer resources; but for other part, I just copy/pasted most links from #"Extension".

Actually, I also removed some old and undeveloped links (https://josm.openstreetmap.de/wiki/WikiStart?sfp_email=&sfph_mail=&action=diff&version=255&old_version=254&sfp_email=&sfph_mail=)

I don't know who wrote https://josm.openstreetmap.de/wiki/Styles#Activatingmorestyles but it is better than "installation instructions" (https://josm.openstreetmap.de/wiki/Help/Preferences/Map#MapPaintStyles) from version 258/238

[openstreetmap.org-user-d1g]

Personally I don't like "installation instructions" as text links:

• they don't describe menu items or respective preference menus ("Imagery" menu, )
• they don't explain what will be installed or preformed (Enable items from "Imagery" menu; Add additional items to "Imagery" menu; Add custom URL in preferences).

Instead, "installation instructions" used almost for every link. IMO we should fix this at very lest, if there no objections.

[openstreetmap.org-user-d1g]

Replying to openstreetmap.org-user-d1g:

And your tabular design simply was ugly

Yes, this is because of wordy sentence like ("Use one of 6 options above, more detailed instructions or learn about download options")

We can use CSS "width" or place hardcoded [ br ] everywhere; I will be absolutely okay with any solution.

Second thing that contributes to ugliness is Tracwiki in that default CSS is not perfect when we use dotted lists inside table/tr/td cells; we can change CSS or simply drop lists and use manual [ br ] of everything when only necessary.

If I'm not good at spacing/layouting things (which it wasn't heavily focused during changes), any other editor can suggest a more fresh design.

Personally, I find lists as more easier to use/update/translate/wikimaintain, therefore I used them instead of multiple-links-hidden-inside-sensenses.

[Klumbumbus]

I have the same opinion like stoecker.

Also things like Scripts are very special. Only very few users use them. This is not appropriate for this start page. "Less is more."

[bastiK]

Hi d1g,

if you plan a major revamp of the start page, you could copy it to a new wiki page, do you changes there, then ask for feedback.

I think it is important to keep the start page reasonably clear and focused. The hudson website you mentioned, for example, doesn't squish all possible links and details on the front page either.

[bastiK]

Replying to openstreetmap.org-user-d1g:

Personally I don't like "installation instructions" as text links:

• they don't describe menu items or respective preference menus ("Imagery" menu, )
• they don't explain what will be installed or preformed (Enable items from "Imagery" menu; Add additional items to "Imagery" menu; Add custom URL in preferences).

Instead, "installation instructions" used almost for every link. IMO we should fix this at very lest, if there no objections.

I don't understand the problem with "installation instructions". Seems clear and useful to me. The individual pages that are linked can probably be improved as most of the stuff on the wiki.

[openstreetmap.org-user-d1g]

Replying to bastiK:

Hi d1g,

if you plan a major revamp of the start page, you could copy it to a new wiki page, do you changes there, then ask for feedback.

I think it is important to keep the start page reasonably clear and focused. The hudson website you mentioned, for example, doesn't squish all possible links and details on the front page either.

Then, I will simply follow "Portals" approach instead of tables.

There will be 3 or 4 portals:

• Learn JOSM (brief overview how it could be extended)
• Use JOSM (1 link to "top resource", 1 optional link to "List of all" (if different)
• Develop JOSM (only most relevant links to extending core JOSM or styles or something else)

[openstreetmap.org-user-d1g]

Replying to bastiK:

Replying to openstreetmap.org-user-d1g:

Personally I don't like "installation instructions" as text links:

Seems clear and useful to me.

Do you really think that ​text or ​search instructions are useful?

Personally, I would name things with their names (if they have good names/verbs).
​Google or ​Google front page or ​google it

[Klumbumbus]

Replying to openstreetmap.org-user-d1g:

Do you really think that ​text or ​search instructions are useful?

This depends on the content of the linked page. If you link to the google front page and name the link "search instructions" then it does not make sense since there are no search instructions.
If you link to a page with installation instructions and name the link "installation instructions" then it makes sense.

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

Replying to openstreetmap.org-user-d1g:

Do you really think that ​text or ​search instructions are useful?

This depends on the content of the linked page. If you link to the google front page and name the link "search instructions" then it does not make sense since there are no search instructions.
If you link to a page with installation instructions and name the link "installation instructions" then it makes sense.

Yes, installation instructions is okay text when it links to "installation instructions", but it is too generic. If we can use more precise text/labels, we should use them

For example. https://josm.openstreetmap.de/wiki/Help/Action/Draw#Anglesnapping

• A (we have page with all shortcuts
• "A drawing tool" vs
• "A mode" vs
• "some mode of A drawing mode" vs
• "some function of A drawing mode" vs
• "some function of Angle snapping in Draw mode"

Nobody hurries you or person who wants to learn right things; by oversimplifying you loose details.

Most of the questions I heard and resonated at forums due to incorrect or incomplete formulations.

Therefore "Tools" or "search instructions" or "installation instructions" is only good as H1-H6 headings, but not as text links.

Is it more clear?

[stoecker]

The JOSM start page has two main functions:

• For users using JOSM:
  • it should allow to find information about the most relevant resources
  • give access to online help
  • give access to the participation stuff (maps, styles, presets, startuppage, tickets, ...)
• For nearly anybody else it should show
  • What's JOSM at all
  • Download, start, ... instructions
  • Developers instructions.

Sub-pages focusing on individual topics are fine. Also having duplicate links at many places is fine. And also describing some topics at multiple places is fine. Not everybody will take the same route.

But the start page must be relatively clear and not overloaded, because people see it first. OTOH it also most not be too spartan for the same reason. I think currently we have a good balance.

[openstreetmap.org-user-d1g]

But the start page must be relatively clear and not overloaded, because people see it first. OTOH it also most not be too spartan for the same reason. I think currently we have a good balance.

"​random link about scrolling preference of users". I don't have similar studies for Wikipedia or this site.

I think "new ticket" link is just spammed in every section but it is always visible (right top screen), no matter 3-4 we repeat it with slightly different intros. As you said, you cannot force users to contribute, there also dedicated menu for very this task - so we should present this list JOSM users at least.

Usability of "This site" section is not clear to me, I would create page with name "Wiki" and explain everything about site/wiki and their logins. Note about greyed footer?.. Why greying it then? :)

[stoecker]

Replying to openstreetmap.org-user-d1g:

I think "new ticket" link is just spammed in every section but it is always visible (right top screen), no matter 3-4 we repeat it with slightly different intros. As you said, you cannot force users to contribute, there also dedicated menu for very this task - so we should present this list JOSM users at least.

It's not clear to me what you want to say.

Usability of "This site" section is not clear to me, I would create page with name "Wiki" and explain everything about site/wiki and their logins. Note about greyed footer?.. Why greying it then? :)

This is based on experience. We have many users registering on this site and never using it. Some even complaining, why they cannot upload data after registering. The "This site" section is an attempt to reduce these issues and it seems it worked at least a bit (still many useless registrations, but no more complains :-)

License information should be stated prominently. It is stated on every page, but that may be too easy to overlook, so it's also at the bottom of the start page.

Many people probably will not scroll down at all, that's why the most important information is in the boxes at the top.

[openstreetmap.org-user-d1g]

Replying to stoecker:

Replying to openstreetmap.org-user-d1g:

I think "new ticket" link is just spammed in every section but it is always visible (right top screen), no matter 3-4 we repeat it with slightly different intros. As you said, you cannot force users to contribute, there also dedicated menu for very this task - so we should present this list JOSM users at least.

I created illustration to my words, it will be clearer.

Many people probably will not scroll down at all, that's why the most important information is in the boxes at the top.

We should lower size "downloading box". Single 1920×1080 screen is overkill for 6 links IMO...

Hudson not only includes all download links, but also manages to mention few latest changes along with help links.

[openstreetmap.org-user-d1g]

Replying to stoecker:

Replying to openstreetmap.org-user-d1g:

Usability of "This site" section is not clear to me, I would create page with name "Wiki" and explain everything about site/wiki and their logins. Note about greyed footer?.. Why greying it then? :)

This is based on experience. We have many users registering on this site and never using it. Some even complaining, why they cannot upload data after registering. The "This site" section is an attempt to reduce these issues and it seems it worked at least a bit (still many useless registrations, but no more complains :-)

Well because this information is in the wrong place, it should be stated where it should be, at registration page:

Quick CSS hack for https://josm.openstreetmap.de/register:

#acctmgr_registerform:before {

content: "THERE NO NEED IN THIS; If you need OpenStreetMap account, go to ​https://www.openstreetmap.org/user/new";

}

And to lower or stop wrong registrations ask some stupid question, like "Please enter name (first/given name) of founder of OpenStreetMap?" or you should add captcha if this will broke one day.

[openstreetmap.org-user-d1g]

Some progress on #12800. I created a top-level "portals" page: Portals

• About JOSM project is a stripped down version of WikiStart (WikiStart was filled with "Help" "download links")
  • Download page was simplified, I also created Source code because it's completely different story (so few would use, so many instructions to explain)
  • Please improve Download#Recommendedoptions - I'm not sure if we can style it here or how.
  • Download portal should contain all troubleshooting information relevant to "first time use" but many caveats are placed at other pages
• I created Extend JOSM page that contains only links to configuration steps and manuals.
• I modified DevelopersGuide slightly to adjust it with other changes.

PS. Portals should be a new front page, with minimal text it is not small already, but it is absolutely unstyled ATM.

[openstreetmap.org-user-d1g]

Replying to stoecker:

The JOSM start page has two main functions:

• For users using JOSM:
  • it should allow to find information about the most relevant resources
  • give access to online help
  • give access to the participation stuff (maps, styles, presets, startuppage, tickets, ...)
• For nearly anybody else it should show
  • What's JOSM at all
  • Download, start, ... instructions
  • Developers instructions.

Please review Portals again, it accounts 5 groups at very least:

• Person seeking for "official info" (for example, a journalist, what project is about, this is not a frequent question). JOSM can be introduced somewhere else ("One of osm editors", "a Java program", "open source project" and so on, there many views on "JOSM" and people involved in this project)
• Person who have no knowledge about JOSM and wants to start using it like every other user, because he was given this link (JOSM promotion)
• Person who uses JOSM but have questions (Help resources)
• Person who wants to extend JOSM, but has no Java coding skills
  • Translation and bug reporting falls here, but it is hard to place it so it would make sense
• Person who can code in Java and looking for Developer portal

I don't know if we have more target audiences.

Replying to stoecker:

Sub-pages focusing on individual topics are fine.

Portals provides an outline what should be located where.

Personally, I hate anything above 5K as front page, a front page should be simple and clean and not overfilled with every single link for "everyone" "just in case" - we all die reading them :)

[simon04]

Big thanks to everyone who is improving the JOSM documentation, including new features, keeping it up to date, reworking confusing stuff. Without appropriate documentation, new features remain unnoticed or are not understood. So thank you for your great work!

---

I'm not very happy with the newly introduced portals and channels. I find the parallel worlds between WikiStart and Portals more confusing than helpful. It's basically the same content just organized slightly differently and (in my opinion) less clearly.

Going through the list of wiki:Portals?version=29:

• "About JOSM" ist copying content from WikiStart, the sub-link to JOSM channels duplicates content from WikiStart#GettingStartedHelp, WikiStart#Contact
• "Get JOSM" links to Download which also WikiStart does (although it could be more prominent)
• "Use and learn JOSM" links to Help which also WikiStart does; JOSM Extensions and installation steps as well as "Learn recent changes" is also listed on WikiStart
• "Extend JOSM" is a huge link list for further readings of WikiStart#Extensions
• "Develop JOSM" links to DevelopersGuide

My suggestions: Remove Portals, About JOSM, Extend JOSM, JOSM channels, and integrate the not-yet-included-otherwhere content (mostly only parts from Extend JOSM) at appropriate other pages. And yes, the section WikiStart#Extensions could get some love (a bit of introductory text, not only linking to "installation instructions" but also to "create your own"). If needed, we can re-arrange/re-group sections in WikiStart.

[openstreetmap.org-user-d1g]

WikiStart cannot replace Extend JOSM page. Other pages can be merged back with WikiStart.

"Extend JOSM" is a huge link list for further readings of WikiStart#Extensions

I added "custom imagery" section, it is not found at WikiStart (and it shouldn't be visible from the front page)

Help/Styles/MapCSSImplementation is huge, extracts at Extend JOSM#Customstylesandpublication may help to quickly scan points without reading a complete page.

I find Extend JOSM topic as not something you would present at the front page (Portals or WikiStart).

IMO front page shouldn't cover every detail of the "Help portal" or "Extent JOSM page" or "Developers porlal". They should be bold, visible links, but not directly present at front page.

WikiStart is overfilled with details and Portals is unstyled and miss some info; a compromise solution would be the best option.

I ran out of ideas how to improve Portals or how to cut details from WikiStart.

I would prefer a static and pretty HTML front page (a la ​http://vespucci.io/ or ​http://ideditor.com/) that leads to corresponding portal.

[openstreetmap.org-user-d1g]

JOSM channels covers WikiStart#GettingStartedHelp, WikiStart#Bugs and WikiStart#Contact under one title.

StartupPage can use JOSM channels link in "Getting Help" section. You cannot point "JOSM channels" so easily with current WikiStart page.

[openstreetmap.org-user-d1g]

Replying to simon04:

I'm not very happy with the newly introduced portals and channels.

I merged channels back with Portals?version=31, is it better?

Not sure if "channels" should be 1. inside "About JOSM" or 2. below "Get JOSM" and "Use and learn JOSM"

[openstreetmap.org-user-d1g]

Information about developers (e.g. Immanuel Scholz) was misplaced at DevelopersGuide (page for new developers and patch guides)

About JOSM#Contributors

[simon04]

Replying to openstreetmap.org-user-d1g:

Help/Styles/MapCSSImplementation is huge, extracts at Extend JOSM#Customstylesandpublication may help to quickly scan points without reading a complete page.

That's why we have Help/Styles/MapCSSTutorial. Extracts of a reference do not seem helpful to me.

I would prefer a static and pretty HTML front page (a la ​http://vespucci.io/ or ​http://ideditor.com/) that leads to corresponding portal.

This will not happen soon. See the discussion in #10760. For me, a clear hierarchical structure for navigation and only one location for a piece of information (DRY, for maintainability) is much more important than one pretty HTML page.

Replying to openstreetmap.org-user-d1g:

Information about developers (e.g. Immanuel Scholz) was misplaced at DevelopersGuide (page for new developers and patch guides)

About JOSM#Contributors

-1 for moving long existing content to a newly created page without further thoughts.

Overall, when comparing wiki:DevelopersGuide?version=21 whith wiki:DevelopersGuide?version=34, I find the new way of organization on this page rather confusing. "Not directly relevant to development" → "Get the source", "Compile source code" – I decidedly disagree.

I would favor profund improvements to specific help topics over shuffling content around and filling lists of lists of links.

[Klumbumbus]

Replying to simon04:

...

+1

My suggestions: Remove Portals, About JOSM, Extend JOSM, JOSM channels, and integrate the not-yet-included-otherwhere content (mostly only parts from Extend JOSM) at appropriate other pages.

+1 To me these are all confusing and superfluous link list pages. Instead of guiding the user to a link list page with no real information it is better to directly guide him to the page wehre he can get all the needed information.

The code snippets at Extend JOSM don't make sense there since they help neither users, which are new to mapcss nor more experienced mapcss users. If you want to write mapcss code you have to look at existing mapcss code and read (atleast parts of) MapCSSImplementation anyway.

Also e.g. "Parentselector - impossible in CSS" why would someone reading this page be interrested if something is possible in CSS? Thats an unrelated and confusing info.

[Klumbumbus]

Replying to openstreetmap.org-user-d1g:

I added "custom imagery" section, it is not found at WikiStart (and it shouldn't be visible from the front page)

It is linked there at "installation instructions" behind "Backgrounds"

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

Instead of guiding the user to a link list page with no real information it is better to directly guide him to the page wehre he can get all the needed information.

Yes, a https://josm.openstreetmap.de/wiki/Help page, but you also need https://josm.openstreetmap.de/wiki/Portals to have links to other portals with "real information" as you say.

https://josm.openstreetmap.de/wiki is not usable right now (you have to scroll and search for the right link among 100s trivial links); https://josm.openstreetmap.de/wiki/Portals is more usable.

First screen at https://josm.openstreetmap.de/wiki/WikiStart is about Download. I don't see good reason for this.

[simon04]

Replying to openstreetmap.org-user-d1g:

https://josm.openstreetmap.de/wiki is not usable right now

Is this your opinion? Or is it based on user feedback?

You also know that the help inside JOSM is context aware? That means pressing [F1] opens the help page for the current context (such as dialog, action).

(you have to scroll and search for the right link among 100s trivial links);

Please enumerate 100s trivial links. I'm happy to discuss moving those somewhere else?

Talking about "trivial" links: comparing wiki:Help?version=143 with wiki:Help?version=300, the length of the page and number of links seem to have doubled/tripled.

[skyper]

Replying to simon04:

Talking about "trivial" links: comparing wiki:Help?version=143 with wiki:Help?version=300, the length of the page and number of links seem to have doubled/tripled.

+1, not really an improvement from version 143 to 300

[openstreetmap.org-user-d1g]

Replying to simon04:

Is this your opinion? Or is it based on user feedback?

It is based on observations, no site about software hides "Help portal" ("Support" or "Guides") link at the front page. JOSM does. It is only present as tiny link at second screen of WikiStart.

​https://knowledge.autodesk.com/support/autocad

You also know that the help inside JOSM is context aware? That means pressing [F1] opens the help page for the current context (such as dialog, action).

Sometimes it's an overkill. Help#Selection was never explained before, few users would click F1 at selection window to read about selection Help/Dialog/SelectionList#Selection and it could be used in JOSM.

It is impossible to unambiguously connect every help material with interface element.

Please enumerate 100s trivial links. I'm happy to discuss moving those somewhere else?

Most of them were addressed at Portals already.

Take a first screen of WikiStart, there a 4 links for every version of JOSM package, they are covered at Download and shouldn't be present at the front page.
4 links consume 132+ pixels. If there just 2 recommended options, users shouldn't be confused with every possible option.

Talking about "trivial" links: comparing wiki:Help?version=143 with wiki:Help?version=300, the length of the page and number of links seem to have doubled/tripled.

Help is not a front page, but help portal.

Help should answer every single question inside JOSM.

---

There too many issues with 143, but anyway.

Help?version=143 presented a reader only with JOSM interface as the only topic he should learn.

As simon04 said, they could get context sensitive help F1 about interface elements without need to clutter Help with JOSM interface materials.

Help page shouldn't do the same job as context-sensitive help does.

There many unexplained Help?version=143#Concepts (e.g. Objects, Conflict, Changeset)

It is fine to have 1000s of links in the help portal, especially when they split in 5 chapters and 19 sections.

Especially when link are described and not labelled as "[object] - this page will explain what object is in detail"

[openstreetmap.org-user-d1g]

A front page should look like this: PortalTiles.

Definitely not as current WikiStart. Possibly not as Portals either.

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

My suggestions: Remove Extend JOSM

+1 To me these are all confusing and superfluous link list pages. Instead of guiding the user to a link list page with no real information it is better to directly guide him to the page wehre he can get all the needed information.

The code snippets at Extend JOSM don't make sense there since they help neither users, which are new to mapcss nor more experienced mapcss users. If you want to write mapcss code you have to look at existing mapcss code and read (atleast parts of) MapCSSImplementation anyway.

I'm not feeling brave enough to translate Help/Styles/MapCSSImplementation. I don't think I will ever will. Especially knowing how often it will get outdated.

I can translate Extend JOSM: it is only a 3K page with single sentence per feature.

Often single example is enough way|z13-15 {... to get a working stylesheet.

[openstreetmap.org-user-d1g]

Replying to simon04:

I would favor profund improvements to specific help topics over shuffling content around and filling lists of lists of links.

Half-empty help portal (Help?version=143 ) is not something I would point new JOSM users after they seen an Introduction.

Introduction should be enough for most of the edits (add several objects, edit some details).

As I said, Introduction is easy to read, Help portal can contain help materials for "expert JOSM users".

There many alternatives in JOSM, therefore we have multiple lists to pick single tool from. Many of these lists are not present in menus, it is unwise to simply remove them as they provide utility not found in context help and window descriptions.

[openstreetmap.org-user-d1g]

More issues with Help?version=143:

1. Context sensitive help is present at Introduction#Thankyou, no need to consume space of Help?version=143 with 3 points how to activate F1 help...

2. Help?version=143#JOSMPlugins is useless, plugin are mentioned every time along text.

Help#JOSMconcepts now includes link to JOSM Extensions and installation steps (not limited to plugins at all)

3. Help?version=143#JOSMinterface misses information from JOSM interface

Help#JOSMinterfaceoverview is more recent; starting screen is not explained at all in 143

4. useless external links in Help?version=143#IntheOSM-wiki (everything is better covered in Introduction and JOSM wiki now)

5. Help?version=143#Openstreetmapingeneral, "Map features" is more than enough; no reason to link main page/faq in this case.

6. Help?version=143#Concepts with only 3 points - horribly incomplete about features in JOSM

7. Help?version=143#JOSMerrormessages section (and Help/ErrorMessages page) should be removed with better messages in JOSM (#12855)

All of them were addressed in Help

[openstreetmap.org-user-d1g]

Wiki materials are usually NOT translated in other languages Translations/Wiki#Statustable.

This means if they translate single page Help?version=300 in Javanese - they will have decent starting point without need to translate every single action/tool/menu.

If translators follow Help?version=143 - they have to translate Help/Concepts/Conflict, Help/Concepts/Changeset, Help/Concepts/Object

As translator, I prefer 300 approach over 143.

Furthermore, JOSM interface should be translated in JOSM translations (Translations) first, not at Help?version=143 page. -1 to any attempt to translate JOSM interface at Help page from me.

[simon04]

Replying to openstreetmap.org-user-d1g:

Replying to simon04:

Is this your opinion? Or is it based on user feedback?

It is based on observations, no site about software hides "Help portal" ("Support" or "Guides") link at the front page.

Not every thing get's better just because it's changed. Did people really have troubles finding the "Help" link?

Please enumerate 100s trivial links. I'm happy to discuss moving those somewhere else?

…
Take a first screen of WikiStart, there a 4 links for every version of JOSM package, they are covered at Download and shouldn't be present at the front page.
4 links consume 132+ pixels. If there just 2 recommended options, users shouldn't be confused with every possible option.

So if it boiled down to removing 2 download options and enlarge the "Help" link in order to terminate the whole portals discussion, I could happily live with that. Yes???

Help should answer every single question inside JOSM.
…
It is fine to have 1000s of links in the help portal, especially when they split in 5 chapters and 19 sections.

This sounds sarcastic to me. But, sadly, I think it is not meant like that. I also don't get why "Recent changes", a random selection of plugins (UtilsPlugin2, ContourMerge, …) need to be presented on the help page. To me, this page does not follow any comprehensible concept, but it seems to be a random aggregation of links from a single user. Please write a ​user diary titled "My favorite JOSM help links in 5 chapters and 19 sections" keep the official help clean.

Replying to openstreetmap.org-user-d1g:

I'm not feeling brave enough to translate Help/Styles/MapCSSImplementation. I don't think I will ever will. Especially knowing how often it will get outdated.

Some pages are not meant to be translated to every language. The whole Java API reference for instance is only available in English: ​https://docs.oracle.com/javase/8/docs/api/

Often single example is enough way|z13-15 {... to get a working stylesheet.

→ wiki:Help/Styles/MapCSSTutorial

---

@stoecker, team: HELP! Which direction should the JOSM help go? Yes, the OSM ecosystem is largely a do-ocracy, but sometimes this goes out of control. We need some kind of decision before the JOSM wiki ends up in a complete mess (I just came across JOSM Extensions and installation steps, a page with superfluous content which is not linked from a single other page)! I don't like the way the whole documentation is evolving.

[openstreetmap.org-user-d1g]

Replying to simon04:

Not every thing get's better just because it's changed. Did people really have troubles finding the "Help" link?

Because they were presented with in JOSM - not so much.

So if it boiled down to removing 2 download options and enlarge the "Help" link in order to terminate the whole portals discussion, I could happily live with that. Yes???

Not really, single link Download is enough (PortalTiles). Why to create A4 to format it in the first place? (WikiStart is overkill for 2 links)

Help should answer every single question inside JOSM.
…
It is fine to have 1000s of links in the help portal, especially when they split in 5 chapters and 19 sections.

This sounds sarcastic to me. But, sadly, I think it is not meant like that. I also don't get why "Recent changes", a random selection of plugins (UtilsPlugin2, ContourMerge, …) need to be presented on the help page. To me, this page does not follow any comprehensible concept, but it seems to be a random aggregation of links from a single user.

As I said, you can read Russian forum to see what is really difficult in JOSM or being asked from other users.

Similarly, you can include most of the answers from ​https://help.openstreetmap.org/tags/josm/?sort=mostvoted at Help page. It will make Help only more valuable and usable.

Some content may be sorted from Help to a more appropriate page if necessary.

Please write a ​user diary titled "My favorite JOSM help links in 5 chapters and 19 sections" keep the official help clean.

They are not mine in the first place. Surely I will continue edits to ​Наглядный JOSM/Самые запрашиваемые инструменты

Nobody ever discussed JOSM interface for 4-6 years as much as in Help?version=143 (60-70% of screen height is about interface elements normally found in JOSM).

JOSM interface is not complex, there little to nothing to discuss or ask questions.

Replying to openstreetmap.org-user-d1g:

I'm not feeling brave enough to translate Help/Styles/MapCSSImplementation. I don't think I will ever will. Especially knowing how often it will get outdated.

Some pages are not meant to be translated to every language. The whole Java API reference for instance is only available in English: ​https://docs.oracle.com/javase/8/docs/api/

Then why to prohibit translation of heading at Extend JOSM?..

Often single example is enough way|z13-15 {... to get a working stylesheet.

→ wiki:Help/Styles/MapCSSTutorial

Irony is that MapCSSTutorial doesn't mention zoom based selectors or other headings from MapCSSImplementation.

I just came across JOSM Extensions and installation steps, a page with superfluous content which is not linked from a single other page)!

version 301 of Help, see edit

I don't like the way the whole documentation is evolving.

Can you please provide some points what should/shouldn't be done?

[openstreetmap.org-user-d1g]

​https://help.openstreetmap.org/questions/1252/rotate-polygon-in-josm

question was voted 8 times
answer was voted 15 times

Pretty much why I created Help#Rotation and explained Help/Action/OrthogonalizeShape#OrthogonalizationisnotRotation

[bastiK]

openstreetmap.org-user-d1g, you did valuable contributions to the JOSM wiki and you have a lot of good ideas. For example the page Introduction has improved a lot.

One core wiki motto is "be bold!". You are taking this a little too far sometimes, e.g. by revamping the start page without checking with the team. Also instead of taking the hints from long time team members to heart, you tend to start long-winded arguments and try to push your view, to the point where it's getting weary.

One general problem is a narrow focus on particular pieces of information that seem important to you, but which feel out of place on the corresponding page.

Replying to simon04:

@stoecker, team: HELP! Which direction should the JOSM help go? Yes, the OSM ecosystem is largely a do-ocracy, but sometimes this goes out of control. We need some kind of decision before the JOSM wiki ends up in a complete mess (I just came across JOSM Extensions and installation steps, a page with superfluous content which is not linked from a single other page)! I don't like the way the whole documentation is evolving.

The ideas on portals are not unreasonable, but I don't see it ripened (now or in near future) to a point where we would agree to abandon the current start page in favor of the portals. Keeping both side by side is not a long term solution.

I would ask openstreetmap.org-user-d1g to stop his/her work on WikiStart, Help, DevelopersGuide and the new pages related to the portals project for some time. Please resist your urge to reorganize and shuffle things on a large scale and focus your contributions on more specific help topics.

[openstreetmap.org-user-d1g]

but which feel out of place on the corresponding page.

We had no guidelines what shouldn't be covered at page A, sometimes page B wasn't created and you have to update several pages and change links from A to B.

Keeping both side by side is not a long term solution.

Most programs tend to pick portals for help desks and "start page" for the front page.

Hudson picked "portals" approach even for their front page (they don't have a fancy front page).

I would like to hear "why?" keeping them (Portals or PortalTiles) wouldn't work for JOSM.

to stop his/her work on the new pages related to the portals project for some time

Sure thing, I would like to hear how PortalTiles could be improved or how to make it more usable.

by revamping the start page without checking with the team

See 12800#comment:17 and 12800#comment:19.

work on WikiStart

BTW, I didn't make any edits to WikiStart for a long time. I started Portals instead of revamping WikiStart (which I did first time).

[bastiK]

Replying to openstreetmap.org-user-d1g:

Most programs tend to pick portals for help desks and "start page" for the front page.

Hudson picked "portals" approach even for their front page (they don't have a fancy front page).

I would like to hear "why?" keeping them (Portals or PortalTiles) wouldn't work for JOSM.

Switching to Portals is a huge change. You need to motivate at least one member of the core team to support the project. I.e. invest considerable time and energy to give detailed feedback, help out with selection of topics, wording, convince the rest that it is a good idea, etc. pp.

[openstreetmap.org-user-d1g]

I think most of the questions raised in #12800#comment:11 are covered in PortalTiles.

Because About JOSM and Extend JOSM were expanded, you don't have to present every link at PortalTiles.

"installation instructions" are now presented just everywhere: Plugins, Presets

Download page was updated too, single link to Download is more than enough for every page; BTW Download is linked from Introduction#LaunchJOSM - no need to over-present it at front page (PortalTiles or WikiStart).

OTOH it also most not be too spartan for the same reason

I'm not sure how to help with it as it is subjective.

[bastiK]

See comment:26:ticket:12801.

This is a backup of the wiki page PortalTiles?version=14:

	Download download steps, troubleshooting during installation		First edit with Introduction Help portal use and learn JOSM		About JOSM what's JOSM at all, project info, source code, list of contributors
	Extend JOSM how to create new extension; basic knowledge of the JOSM configuration, no real Java programming		Develop JOSM plug-in development and other tasks that require at least basic Java programming skills		Contribute Translate: JOSM program and wiki, presets, start-up page and older JOSM news Suggest new features, submit your idea using New Ticket link in the top right corner, DefaultPresets - how to suggest new tags and new icons Report bugs from the program using respective button in "Help" menu, so that developers can easily reproduce them.

[openstreetmap.org-user-d1g]

Replying to bastiK:

is a backup of the wiki page ...

Thank you!

I couldn't do much because of tracwiki styles and missing icons for every tile. If we have more experienced editors than me, I would like how they improve this table.

[openstreetmap.org-user-d1g]

Replying to simon04:

I also don't get why "Recent changes" ... need to be presented on the help page

Every sane documentation/help does this. E.g. osmand, qgis, autocad, ​carto or JOSM (Changelog).

Usually it is called "migration guide version a.b to c.d". "New in c.d"

Sometimes it is done multiple times from various perspectives:
​http://www.autodesk.com/products/autocad/compare/compare-releases
​http://help.autodesk.com/view/ACD/2016/ENU/?guid=GUID-1B228E5E-AD48-4CE9-B844-9D2406C60AC6

[Klumbumbus]

I made a few small adjustments suggested by d1g to the wiki start page (e.g. reorder and short explanations of the extensions). For more clean up, the last 4 chapters shoud be reviewed. There is some duplicate content. Maybe the chapters "Found a bug?", "Contribute" and "Contact" can be merged to two or one chapter.

[openstreetmap.org-user-d1g]

Replying to Klumbumbus:

I made a few small adjustments suggested by d1g to the wiki start page (e.g. reorder and short explanations of the extensions).

Thank you!

about bastiK edit: I still think that we could show more information at the first screen from the top (less white space), but I could live with it easily.