Distinct project specific help pages with only these plugins

[danthe1st]

Suggestion

In the current documentation page, there are many projects shown so people visible may be overwhelmed from the amount of elements in the table of contents.

To make the help page more usable, I suggest:

• Allow to create links that only show parts of the projects and allow expanding the others. For example, a link to the help for "Eclipse usage for Java developers" would only get the "Eclipse Platform User Guide", "Java Development user guide" and "EGit Documentation" as well as a single entry telling them that more entries are hidden and allow expanding them. I would imagine this looking like the following:
• Show these links in the package list, the installer as well as in the IDE itself (preferably in the welcome screen or the Help toolbar). There should be a different link for different Eclipse installations (e.g. Eclipse for Java and Web Developers should include more categories than Eclipse for Java Developers).

Essentially I'm looking for the existing scopes feature but with stable links that are also used in commonly accessed pages (apart from me not being able to use that feature for some reason).

Community

• [X] I understand suggesting an enhancement doesn't mandate anyone to implement it. Other contributors may consider this suggestion, or not, at their own convenience. The most efficient way to get it fixed is that I implement it myself and contribute it back as a good quality patch to the project.

[HannesWell]

Thank you @danthe1st for this issue. I transferred the issue to platform.ui but since the doc itself is distributed it might have to be moved again at https://github.com/eclipse-platform/eclipse.platform.releng.aggregator or just https://github.com/eclipse-platform/eclipse.platform since the org.eclipse.help plugins reside there (the structure is not always ideal).

In general I share your assessment that the help is often overwhelming and reducing the entries would probably help more often than it would cause harm.

Since one can already encode the topic (i.e. the 'main' entry) in the URL I think it would definitively be feasible to encode more information, like a list of primary_topics (or alike) that if present is rendered as you suggested. These links could then be added at different locations. Selecting the exact primary content for different topics could then be a kind of controversial discussion.

What do the others think?

Personally I'm not very familiar with how the help works but maybe someone more familiar with it can give some guidance?

[danthe1st]

One thing I could imagine some way to get from running Eclipse (e.g. the "Welcome" screen or the "About" page) to the documentation site containing only information about plugins currently installed (e.g. show Eclipse (plugin) development stuff only if PDE or similar is installed) and do the same with the package pages (include a link to the docs including only what's in the package).

The question is how many topics that would result in and how many of them are actually relevant to most people. Removing some of them that would be included in the installation would then be the controversial discussion you mentioned.

[HannesWell]

One thing I could imagine some way to get from running Eclipse (e.g. the "Welcome" screen or the "About" page) to the documentation site containing only information about plugins currently installed (e.g. show Eclipse (plugin) development stuff only if PDE or similar is installed) and do the same with the package pages (include a link to the docs including only what's in the package).

If you use the help delivered with each installation of Eclipse via the Menu -> Help -> Help Contents you get exactly that already. Of course you can only use that after downloading a specific package and not in advance or check it online.

The question is how many topics that would result in and how many of them are actually relevant to most people. Removing some of them that would be included in the installation would then be the controversial discussion you mentioned.

You can probably answer the first question by downloading some of the available packages and check their Help as described above.

In general would you be interested to work on enhancing the link arguments to show only a reduced number of topics? A good starting point are probably one of the search results in https://github.com/search?q=repo%3Aeclipse-platform%2Feclipse.platform%20topics&type=code

[danthe1st]

If you use the help delivered with each installation of Eclipse via the Menu -> Help -> Help Contents you get exactly that already. Of course you can only use that after downloading a specific package and not in advance or check it online.

My bad, I didn't notice that.

In general would you be interested to work on enhancing the link arguments to show only a reduced number of topics?

I don't know whether I'm able to get a development setup running or actually have the time to implement it but I guess I should be able to take a look at it at some point.

[HannesWell]

In general would you be interested to work on enhancing the link arguments to show only a reduced number of topics?

I don't know whether I'm able to get a development setup running or actually have the time to implement it but I guess I should be able to take a look at it at some point.

No need to rush, but it would be great if you give it a try. CONTRIBUTING.md of this repository should lead you to the required information. Don't hesitate to ask if something is unclear.

[danthe1st]

I think the one issue I was facing is scopes seem to only work when the documentation is opened in a local Eclipse installation but not on https://help.eclipse.org/ (on the website, scopes don't seem to be hiding any top level elements).

What I think could be done (which I think should probably be discussed before implementing it) is:

• make sure that scopes work on the website (Is this an issue only I am facing or is this broken for everyone?)
• create a few default scopes
• introduce a few default scopes for the website (e.g. ones with everything installed for different selection in the installer)
• allow creating a permalink to https://help.eclipse.org with a specific (default) scope selected.

At least when I originally created this issue, I was mainly thinking about the online documentation.

[HannesWell]

• make sure that scopes work on the website (Is this an issue only I am facing or is this broken for everyone?)

That sounds good. But AFAICT scopes are nothing that's implemented yet. A local Eclipse simple shows what's installed and therefore available. If we want that online, it has to be implemented. But this doesn't mean it's not possible or not wanted. :) In general you can already link specific topics or even pages:

• https://help.eclipse.org/latest/index.jsp?nav=%2F3
• https://help.eclipse.org/latest/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fant%2Flaunching%2Fpackage-summary.html&cp%3D3_1_0_0

But to be honest. The links are not nice and not easy to read.

Your other points also sound good, but should consider what's available and what not.

[laeubi]

But to be honest. The links are not nice and not easy to read.

Just as a hint, if you right click on the navigation entry and choose "copy link" (actual text might differ depending on browser/os/locale/...) you get a slightly more nicer one:

https://help.eclipse.org/latest/topic/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/ant/launching/package-summary.html?cp=3_1_0_0

The appended query string can be omitted (not sure what it is used for) and you finally get

https://help.eclipse.org/latest/topic/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/ant/launching/package-summary.html

[danthe1st]

But AFAICT scopes are nothing that's implemented yet.

If it isn't implemented, it may be better to generally remove the UI for it on the online help (at least until it is implemented).