Community
Participate
Working Groups
Created attachment 278429 [details] ABAP Development Tools release notes after applying update 1) Motivation Our main goal as developers should be that new features are actually getting used by our users. However, quite often new features are hard to find. Therefore, software like Eclipse offers release notes: https://www.eclipse.org/eclipse/news/4.10/. We have done the same for our tools but noticed that a lot of users do not read them or even know where to find them. Why should we hide our work? In contrary, we should actively promote it! When you update popular software such as Google Chrome, Firefox or Visual Studio Code the release notes are automatically shown after an update. Users can immediately see what changed and things like animated gifs make release notes more exciting and fun to read. Example: http://ubuntuhandbook.org/wp-content/uploads/2017/08/vscode-1-15.jpg In order, to improve the usage of our tool we are following the Visual Studio Code approach and display the release notes in a separate tab directly after an update got applied. Our solution -> see attachment! The separate tab allows the user to leave the release notes open, continue working and later come back and have a look at them. So far, the feedback we have received has been very positive e.g. https://twitter.com/pixelbase/status/1093871487101095942 We are currently using our own custom implementation. We would love to move it into the Eclipse platform and suggest that the Eclipse release notes are directly being shown after an update as well. 2) Our current solution a) When do we show the release notes? The release notes are shown immediately after the start of eclipse. The information, if the release notes were already shown, is stored in the workspace preferences. With each update of the feature the preference value changes. b) How do we show the release notes? We show the release notes in the editor area. The content of the release notes is a normal eclipse help page. Thus we would like to show the release notes help page in the editor area as an independent part (meaning the content does not change depending on the context). Unfortunately this is not possible with the eclipse help framework (as far as we know). Instead we implemented the release notes as an own EditorPart, which contains only an SWT Browser. This Browser shows the eclipse help page (this requires, that the plugin is not an archive). The Browser has a LocationListener, which opens the normal eclipse help when the user clicks a link in the release notes (this requires a specific structure of the eclipse help, which is fulfilled by the SAP help plugins). This means, that our current implementation is a quite specific hack and not a general solution. 3) Target solution a) Instead of the current own EditorPart, we would like to show the release notes as a normal Eclipse help page. They should be shown immediately after installing/updating plugins b) Release notes should be accessible via a menu entry under "Help -> Release Notes..." similar to "Help -> Tips and Tricks..." c) We need a concept, how the release notes can be used by multiple features (Eclipse, JDT, ADT, …) Do you agree with our target solution? Do you have additional requirements?
AFAIK, if you install something like EGit it will show the Welcome page with the items (among others), that got newly added. You could probably just contribute a link to the release notes. It definitely needs a main option to disable (or enable) this.
(In reply to Dani Megert from comment #1) > AFAIK, if you install something like EGit it will show the Welcome page with > the items (among others), that got newly added. You could probably just > contribute a link to the release notes. Yes. We know that possibility. But the release notes are quite hard to find that way and it needs quite some clicking. You fist have to find the "What's New" menu entry on the welcome page. (1 click) Then you select one "feature" e.g JDT" (2 click) And then an external browser opens up. Now the user is in another application and completely out of context. Compare to our proposed solution. Eclipse starts up. One (or maybe multiple) Editor Tabs are open. The use has at max 1 click to read the release notes. If he does not like to read them now the user also can decide to just keep the "Release Notes Editor(s)" open and read them lager > It definitely needs a main option to disable (or enable) this. Sure we can offer that. But the default should be "show release notes at startup".
Just to be complete I simply paste Michael Istria's mail form the dev-mailing list here: <quote> Hi, I think it's an interesting topic, but having a generic, reusable, extensible, consistent, appealing... solution that works for the whole IDE seems very hard to me and requires a lot of design effort both in UX and extension-points/API, for a return on investment that I think is questionable. Would RCP providers for instance like to enable auto-update of the internal help for each upgrade of each module? Do they actually want such small grain of information for their users? Isn't it better to leave it as a product-specific or branding task? Would plugin developers (like m2e for instance) spend the time writing such N&N for inside Eclipse IDE when they basically don't even write one currently as plain HTML or wiki pages? I'm afraid that the adoption rate of such N&N extensible model would be very low, compared to the amount of effort it requires. I think instead of a framework, we should consider a simpler case of just enabling such feature in the Eclipse IDE, linking to existing N&N pages upon upgrade. It could be an addition to the EPP package and just consuming the current "source of truth" that's available, at https://www.eclipse.org/eclipseide/2019-03/noteworthy/ by showing it in a browser editor. </quote>
I can imagine that this would be more valuable to others, when just focusing on the "display help in an editor part instead of view" functionality. That should be re-usable for everyone. Everything else (what to display, when to open it automatically, how to store the information the user has already seen this) might be very product specific.
Created attachment 278432 [details] Update Process with org.eclipse.intro (In reply to Matthias Becker from comment #2) > > Yes. We know that possibility. But the release notes are quite hard to find > that way and it needs quite some clicking. You should take a second look at the org.eclipse.ui.intro.* extensions points. Whenever we release new code the info part is popped up and users can click the link to our release notes. See attachment
I see that the community is not interested in a generic platform approach. Then let's focus on 2b: "Thus we would like to show the release notes help page in the editor area as an independent part (meaning the content does not change depending on the context). Unfortunately this is not possible with the eclipse help framework (as far as we know)." Can someone of of the help experts give us help in that area? Maybe we miss something and it is possible in fact. If it's not possible we ware willing to contribute an API but we would also need some help from your side. @Alexander: Can you help here?
I think we should fix the IMHO ugly welcome screen and make it an normal editor. This editor could open after installing new stuff. Having two different solutions for news feels wrong and in its current state the welcome page feels useless to me.
(In reply to Lars Vogel from comment #7) > I think we should fix the IMHO ugly welcome screen and make it an normal > editor. This editor could open after installing new stuff. > Can it be declared in org.eclipse.e4.ui.intro as a reusable control that listens for a [number of] topics? And then wrapped with E3 IEditorPart in org.eclipse.ui.workbench to be used in the current majority of eclipse applications. As you know, currently it is not realistic to create E4 application with IDE functionality. IMHO the need to improve the E4 story with every new API.
(In reply to Alexander Fedorov from comment #8) > Can it be declared in org.eclipse.e4.ui.intro as a reusable control that > listens for a [number of] topics? And then wrapped with E3 IEditorPart in > org.eclipse.ui.workbench to be used in the current majority of eclipse > applications. > > As you know, currently it is not realistic to create E4 application with IDE > functionality. IMHO the need to improve the E4 story with every new API. Sounds good to me, lets discuss in Bug 547499.
(In reply to Lars Vogel from comment #7) > I think we should fix the IMHO ugly welcome screen and make it an normal > editor. This editor could open after installing new stuff. When I today open the Eclipse IDE for the first time (after an update) the welcome Screen comes up with a lot of content. Only one link leads to "What's new" So you click on this link (one click) then you see a page with further links. One of them e.g. is the link for new in JDT. Now you click on that (second click). And now an external browser opens. Our ABAP Development Tools already have "What's new" Documentation from the beginning on and it was integrated in this "What's new" section on the welcome page. But this is too far away: User have to click 2 time and then the external browser opens. We found out in a user survey that almost nobody found our "What's new" documentation. We also found out that user lover our current solution (showing the What's new content directly in the editor area automatically). So I would say "fixing the welcome screen to a normal editor (and keeping the content the same) does not help here. > Having two different solutions for news feels wrong and in its current state > the welcome page feels useless to me. I don't see this as "useless".
I agree with Matthias that we don't need to change the Welcome Page for what's new and starting from a fresh new workflow/editor would give better results with less efforts.
(In reply to Mickael Istria from comment #11) > I agree with Matthias that we don't need to change the Welcome Page for > what's new and starting from a fresh new workflow/editor would give better > results with less efforts. If Mickael and Matthias are for this new editor approach, I change my optinon. +1 for this new editor approach. Would be great if this could be consumed in e4 as Alexander suggested.
Thomas, one more answer to your initial question: How to simplify the approach of showing the release notes in the editor area? Open them in a browser. PlatformUI.getWorkbench().getBrowserSupport().createBrowser("my.browser").openURL(new URL("http://eclipse.org")); I've seen this technique used by Yakindu statechart tools to display release notes after version upgrades, for instance. If you maintain your help via some markup that is understood by mylyn wikitext, you can easily generate the help document as well as the separate HTML page from the same source.
