The ABAP Keyword Documentation gets a new design (part 3)

[lenapadeken]

When we started sharing the news about the redesign of the ABAP Keyword Documentation, we got a lot of feedback from you. Your feedback focused on whether the content was made for beginners or not, whether examples were too complicated or just right, and, of course, the main topic of the blog: Design. In the comments, you shared no criticism of the ADT version, but a lot of criticism of the Web and Help Portal versions, which use the SAP UI5 (short UI5) framework. With this blog post, we are sharing the current version and you will see some changes based on your feedback.

Approach

The first prototype we built with a new documentation layout was a static UI5-based HTML file. After figuring out that we can implement the framework in a single HTML file, we build a first XSL transformation from XML to HTML.

Outcome

Here are some examples of how the new design compares to the old design. Overall, the following changes have been made:

• The hierarchy tree (TreeTable) can be expanded, collapsed, and hidden.
• Keyblocks are implemented using forms (SimpleForms).
• Source code in keyword topics:
  
  • You can copy code by clicking a button.
  • You can run examples by clicking a button (future feature).
• Notes are displayed by messages (MessageStrip).
• If a topic is not found, pictograms with an error message (IllustratedMessage) are displayed.

Header

The following image shows the header element for the new layout:

Header UI5

Result

• Each topic has a version drop down (ComboBox) to toggle between language version and ABAP release.
• You can switch to dark mode by clicking the color palette button.
• You can copy the URL by clicking the button at the top right.
• Each topic has a label for the topic type (e.g. Keyblock).
• Some topics have related links (currently these are the Continue links).
• If a topic has additions, alternatives, or variants, a tab bar appears to quickly switch between the options.
• If the topic contains syntax forms, they are displayed in containers so you can easily scroll through them.
• Glossary topics display domain-specific labels (InfoLabel) in the header. This is a new feature and you can also see it in ADT with ABAP Release 7.96, SAP BTP ABAP Environment 2405.

Troubleshooting

Problem	Solution
The header takes up too much space.	Collapse header.
The header does not stay on top.	Pin header.

Tree and search bar

The following image shows the tree and the search bar for the new layout:

UI5 Tree and Search

Result

• Search now supports type-ahead searching.
• A result list is displayed when you press Enter.

UI5 Result List

Troubleshooting

Problem	Solution
The tree is taking up too much space.	Hide tree.
The tree is not displayed.	Show tree.

Keyblocks

The following image shows a keyblock for the new layout:

UI5 Keyblock

Result

• This keyblock does not look much different than before, except for the emphasis on important notes, like the Caution message strip here.

The following image shows an Example keyblock for the new layout:

UI5 Example

Result

• Examples are now displayed in dedicated code editors.
• You can view the result of the example in the future by clicking the button with the arrow.
• You can copy the example by clicking the button with the document icon.

Tables

The following image shows a table for the new layout:

UI5 Table

Result

• This image shows one of the relatively new feature tables (e.g. RAP Feature Tables in the ABAP Keyword Documentation). It contains many entries and so with the UI5 framework, the content can be structured and navigated to much easier.
• Note also that scrolling through the entire topic is enabled again.

Glossary labels

The following image shows a glossary entry for the new layout:

UI5 Glossary Entry

Result

• This image shows several labels for the domain of the glossary entry.
• You can navigate to any glossary.

Error message

The following image shows an error message for the new layout:

UI5 Error Message

Result

• The error message will tell you exactly what went wrong, such as why you cannot see the documentation. Again, you can simply change the version in the drop-down menu if the error is Language version.

Overview

The following image shows the entire page for the new layout:

UI5 Overview

This is how far we've come on the design journey for the UI5 version. Suggestions for improving the layout? Comment down below.