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
Related blogs:
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:
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.
The ABAP Keyword Documentation is written in ITF and stored in the database tables
As mentioned above, we extended the ITF to HTML converter by adding a conversion from ITF to XML and transformations from XML to HTML.
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!
The screenshot shows our first suggestion of a (hard-coded) UI5 design for the documentation.
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:
As we have four different output formats, we came up with two solutions:
We expect the following improvements:
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 F1_Help@sap.com.
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.
What do you think? Comment down below or use one of the options mentioned above.
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.Related blogs:
- Blog for the ADT version
- Blog for the Web and Help Portal versions (in preparation)
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.
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:
- A new simple CSS design for the ADT version (the most frequently used version)
- 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 F1_Help@sap.com.
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.
- SAP Managed Tags:
38 Comments
