The ABAP Keyword Documentation has been around for many years and is the first resource for ABAP developers searching for ABAP keywords, syntax, or release-specific changes. Pressing F1 on a keyword, calling transaction abaphelp or abapdocu, or looking up content in the Help Portal are usual entry points. All versions look the same but are not the same. During this blog series, you’ll witness the changes the new design will bring and have the chance to be part of it.

(At least two more blogs are in preparation. One for the ADT version and one for the Web and Help Portal versions. Future blogs will be listed here.)

Background

In 2021, the ABAP Docu team surveyed the interaction of users with the documentation. As a result, the majority wished for a more modern documentation design. You could more or less summarize the feedback in the following sentence:

The documentation looks like it’s straight out of the 80s.

Even though it was first available in the 90s. Of course, this is not feedback you want to receive, but we know change is needed. The reason for the simplistic design was simply a lack of resources. Luckily, this changed, and in late 2021, we started by giving the current layout a slightly more modern look. Here is a screenshot of the design.

Current design of the ABAP Keyword Documentation

Still, we were not satisfied with the look and feel of our output. There is more potential with all the HTML frameworks available today, and with our own infrastructure, we can easily change the way content is generated. Instead of using string processing to add inline CSS to HTML, we could use a different format: XSLT (eXtensible Stylesheet Language Transformation). One advantage of XSLT is that we can arrange content depending on our needs and structure our content differently from the XML input. But for this to work, we would need an XML document as our source input. Our source input is ITF (Interchange Text Format). Fortunately, we can simply convert ITF to XML. Switching to XML would have another advantage, which is that we could decouple our documentation from ITF. Let’s take a step back to understand how our documentation is written and displayed up to now.

Technical background of the ABAP Keyword Documentation

The ABAP Keyword Documentation is written in ITF and stored in the database tables DOKIL, DOKHL, and DOKTL. Each topic is currently converted to HTML by the ITF to HTML converter. The converter outputs a download version, which is used as the Help Portal version, and three separate output versions for SAP GUI, an ICF version, and the ADT version. What is special here is that the converter and all output versions are maintained in the AS ABAP. The diagram displays the hierarchical structure of the documentation output management.

Old documentation infrastructure

As mentioned above, we extended the ITF to HTML converter by adding a conversion from ITF to XML and transformations from XML to HTML.

Approach for creating a new layout for the ABAP Keyword Documentation

Quite simply, we were starting from scratch and with a trial-error mentality, which fairly early showed its limitations. Our first approach for a better layout was a simple change in the CSS. After this, we tried a first SAP UI5 (short UI5) setup. With this, we ran into issues like the folder structure of UI5, which we could not pass as an HTML string. This solution would not pay off for our use case. Luckily, there’s a version of UI5 that’s putting everything in one HTML file. In XML terms into one topic. Perfect!

Hard-coded SAP UI5 example

The screenshot shows our first suggestion of a (hard-coded) UI5 design for the documentation.

High-level goals

Before we started our journey towards a new infrastructure and design, we thought about the main aspects and chances we would get from the change:

• Fresh and youthful look
• New functionalities
• Improved functions
• Integrated semantics

Steps to take

As we have four different output formats, we came up with two solutions:

1. A new simple CSS design for the ADT version (the most frequently used version)
2. SAP UI5 design for the ICF version and Help Portal version (accessed in browser)

Improvements

We expect the following improvements:

• Modern design
• More functionalities
• Easier and faster maintenance of the layout
• Easy decoupling of ITF if desired

Resulting in each of the items is an improved user experience. User experience was the reason we started this journey and will be the reason for future changes. Since you are an important part of shaping the future, we value your feedback. You can give us feedback by using the Mail Feedback button or sending us an email to [email protected].

Sneak Peek

This would not be a complete blog without showing you a sneak peek of the future documentation layout. The ADT output is already officially released with ABAP Release 7.93, SAP BTP ABAP Environment 2308.

ADT design

SAP UI5 design

What do you think? Comment down below or use one of the options mentioned above.