The ABAP Keyword Documentation gets a new design (...

lenapadeken · ‎10-24-2023

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.

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.

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. 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:

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.

this_yash · ‎10-24-2023

Looks slick 😍

Sandra_Rossi · ‎10-24-2023

To be honest, I don't really mind about the look and feel of the documentation, my concern is more about the content and the quickness and easiness of finding and understanding the information which is probably the most important problem of people looking at the documentation. Of course, it means a complete rethink and revamp of the contents.

DominikTylczyn · ‎10-24-2023

I'm with you on that. It can be rusty and old looking, but it has to be accessible and rich in content.

Jelena · ‎10-24-2023

Thank you for sharing! Not sure who was surveyed in 2021 but as someone who was actually alive in the 80s :), I can say that maybe people who say stuff like this are not the right demographic to base decisions on.

I'd like to echo what sandra.rossi and 3a9e4ce873a94034b33dc62b0ce600ee stated: it's more about the content and ease of use than about which decade the looks belong to. Personally, I have no problem with purely visuals and actually enjoy simplicity here. Documentation is not the place to flex design muscles unnecessarily.

I can also understand and appreciate the challenges of maintaining documentation to be exposed in different environments. This is not a concern for the companies with flashier looking Help web pages.

In the screenshot examples, ADT one looks better to me. To be honest, I'm not a fan of UI5 design in general with header and tabs. It's like VA01 called. 🙂 It takes up space and offers no value. In fact, I feel there is nothing wrong with having just the straight document-looking text. Also in UI5 example, the location for Version and copyright info is very weird.

Most of the time, I just need to look up a command quickly. If I google "SHIFT command in ABAP", below is what I see in the 2nd top link. (The topmost one is for shift_left/right functions, which is a general problem with Google search quality these days.) There is no navigation tree on the left, no way to select a different version. Just to read about the command, this is fine. But I do wish there was a better code example. Or at least maybe tell us what the output of the code example is supposed to be?

Also, some articles in Help really could use a TLDR or ELI5 version. I don't have a specific example right away (they're not hard to find though) where I'd start reading and be puzzled by what the text is trying to say. I think a lot of these articles are too academic. I do understand there is a need to have super thorough and precise documentation for legal reasons or whatever. But still it should be suitable for human consumption.

Thank you!

wridgeu · ‎10-24-2023

Hey there! Love that there is movement going on in this area! 🙂

As some have pointed out already I too don't mind the current design at all. Of course it is no comparison to some of the very modern framework docs out there (especially in the UI/Web area) but it does its job. Don't get me wrong I'm not against change! 😉

Whats most important and always has been is the content and the ease of finding it. I felt that looking at the documentation from the browser was always very cumbersome.

No great language versioning where I found myself checking the breadcrumbs if they existed/worked or the link where the ABAP version was mentioned in (Nice to have something like UI5s docs where I switch the version on the top right which seems to also be in the preview, nice!).
Broken cross-links and unable to open links in a separate tabs (e.g. pressing mouse wheel)
Unable to easily search for something from within the docs. I usually ended up googling again and re-opening whatever else random abap versioned link that popped up ^^
An issue only ABAP has and (for now) continues to have will be the demo sections and executing the code. Aside from whats out there by lars.hvam this won't be possible even in the future.
Code snippets, examples and the explanation "why" or "how can it be useful" is lacking at some points (which docs don't have that problem though?) and the first mentioned point isn't that much of an issue when opening up the docs from within the system, where you can even go straight to performance trace examples or debug demo snippets (I know there are various demos and demo packages - just saying)
EDIT: Adding a way of a global search via CTRL+K like many other docs have it, would also be very awesome and help in navigating all the content.

With that being said. I really like the sneak-peak from the eclipse version! Though I love UI5 I fear that the tree on the left could become too deeply nested for some topics? For the content I personally prefer everything in one page where I can easily CTRL+F and scroll up & down instead of switching from tab to tab trying to find what I'm looking for (maybe make the layout switchable - could be a feature of the future ...). But it's a start and I'm all here for it!

BR and thanks for taking this on!

Marco

Former Member · ‎10-24-2023

jelena.perfiljeva2 and jelena.perfiljeva2 said it all 🙂

Also like the Eclipse design.

larshp · ‎10-25-2023

A: SAP introduced the Open Documentation Initiative in 2021, which allows for easy feedback and fixes. This might be one step towards it, but why not go all the way?

For fixes, I recently was unable to lookup behavior for SET BIT outside of the length of the object, this would have been a nice addition to define the behavior in the help documentation. Also was unable to find when SELECT FROM view ORDER BY PRIMARY key was allowed.

B: Suggest doing real syntax diagrams, I got an example for SHIFT at https://syntax.abaplint.org/?filter=shift#/abap/statement/Shift

C: Easy sharing of links, currently if copying the url, it doesnt always show what the page is showing

😧 Suggest optimizing the content, I like reading from top to bottom, and having as much information in one page as possible, note this also allows for easy Ctrl+F

E: make the examples run inside the html page, example at https://transpiler.abaplint.org

F: instead of screenshots, suggest putting the example on the public internet, I guess it doesnt contain confidential information, then it would be easier to grasp the look and feel

PRAGSMATIC · ‎10-25-2023

Please publish a version on the GitHub publicly so that AI tools can grab them. It is better asking AI than finding yourself for me.

marcfbe · ‎10-25-2023

Thanks, Lena, for the blog. Contrary to other comments, I think the content of ABAP keyword documentation is actually very detailed and describes many edge cases of language features. So thanks to the writers.

I'm a huge fan of "Build in Public". Your blog i.e. SAP's communication strategy seems to go the opposite direction. You tell us the results after the fact... what happens to the feedback now? Sounds like it's too late (or you have tons of things to re-do).

It's interesting how SAP produces documentation, but honestly, I don't care about it. Only results matter. This is where SAP seems to be stuck in the 80s! Shipping the docs in every single ABAP installation around the world is the 80s. It's even in QA and Production systems where literally no one uses it. How much precious HANA disk space and memory is wasted in let's say 100,000 ABAP systems globally? How could anyone outside SAP contribute fixes or new content?

So free yourself from the past, drop the docs from all DOK* tables, and put them on GitHub like the rest of the world. Just Do It. The community of SAP ABAP developers will thank you.

Sandra_Rossi · ‎10-25-2023

After reading marcbernardtools comment "Contrary to other comments, I think the content of ABAP keyword documentation is actually very detailed and describes many edge cases", I'd like to complete my view on "my concern is more about the content": I don't mean the documentation is not good. I find it very good, but a reader must spend a lot of time to understand its organization, the specificities of each precise term. It makes it very complex for newbies to understand it.

So, I really like the precision of the documentation, but I think there can be some huge improvements in the organization. Of course, it's very complex and time-consuming to improve it. All the comments in this blog post give good advices about where are the things to improve.

Sandra_Rossi · ‎10-25-2023

I agree with all, but what do you exactly mean concerning C (I don't remember a case where it doesn't work) and D (example?) + what is this red screenshot supposed to illustrate? Thanks.

wridgeu · ‎10-25-2023

I 100% agree with you. 🙂

marcfbe · ‎10-26-2023

The keyword doc is a reference, so nothing for newbies. That would not be different at MDN JavaScript for example. Still, I agree, that it's difficult to find pages in the tree even for me. A better search would be most appreciated 🙂

There should be a "Guides" section like MDN Learning Area to get an introduction to ABAP. It's where documentation meets learning. But since it's a different department at SAP, there's a different website for it. sigh

larshp · ‎10-26-2023

C: hmm, perhaps it has been fixed, but I've had trouble with this previously

D: The red is all the wasted space, the actual interesting content to be read is 20% of the screen space

lenapadeken · ‎10-26-2023

We recently started working on a Guide that explains ABAP Concepts. There's not much content yet, but it will grow over time (https://help.sap.com/docs/abap-cloud/abap-concepts/about?version=abap_cross_product).

horst_keller · ‎10-26-2023

Hi Marc,

Currently, the ABAP Keyword Documentation has to fulfill two requests:

acting as a manual for ABAP programmers
serving as a complete reference documentation for the ABAP language that can be relied on by hotliners to answer claims such as "SORT itab" does not work.

What we are missing in fact is a division of these parts. But we are already thinking about it. We have to have a separated manual part, that offers direct help and explains the most common use cases and that might be located in an open repository where users outside SAP can contribute. But we still need a reference part where all the nitty gritty is explained in which users outside SAP are not interested in for their daily work. There are also good reasons, why the ABAP Keyword Documentation is system documentation stored in the system, and yes there are reasons against that. Be sure, we are discussing these things already.

And what we also need is an ABAP User's guide for a top-down access, yes, yes ...

Kind regards

Horst

lenapadeken · ‎10-26-2023

Thanks for your feedback!

First small change, more to come:

esjewett · ‎10-26-2023

I like the look and feel, but I must say I'm very concerned about the layout of the web-based keyword documentation shown here. My rough estimate is that only about 30% of the space on the page is dedicated to the actual content that the person using the documentation needs to read.

Navigation appears to merit as much space as the content and it doesn't appear that there is a way to collapse the navigation (I'm not sure what that hamburger button in the upper left does, but it doesn't seem aligned with the navigation pane in a way that suggests it will collapse it). Collapsing the navigation should definitely be made possible.

I'd suggest that you consider getting rid of the header content in the object page layout entirely. Most of it is empty space that takes away from the content and the syntax would be better positioned, more readable, and (I suspect) significantly more accessible to screen readers if it was part of the main content.

Additionally, I would suggest moving away from the tab navigation and going back to the standard object page layout where the content sections are displayed in a single scrollable page and clicking on the tabs scroll the content to the relevant anchor within that content. This would allow a user to read the documentation more smoothly, and be able to compare different syntax variations by either scrolling or using the tabs. Additionally, it would likely improve accessibility.

Another way to say this last suggestion is that the content in the object page layout should look just like the Eclipse version of the documentation (which looks pretty good).

My last suggestion is that you move the copyright notice to the header, to the bottom of the navigation pane, or to the bottom of the content area. In your updated example it is a footer, which means it always obscures the content area, further reducing the already small area of the window dedicated to the content that the user needs to see.

I think if you make these changes you might be able to bring the content area up to 50% of the page with navigation displayed, and possibly as high as 70 or 80% of the page with the navigation hidden.

Good luck!

Ethan

esjewett · ‎10-26-2023

Oh, one last suggestion: In neither this version nor the current ABAP Keyword Documentation does the navigation hierarchy indicate which page in the navigation hierarchy you are currently looking at. Would it be possible to bold or otherwise highlight the "SHIFT" node in the hierarchy if we are looking at the "SHIFT" page?

Thank you!

pokrakam · ‎10-26-2023

I can echo some of the sentiment expressed in the comments: I like the "80's" style (even though this is far more advanced than the Internet was back then).

ABAP Documentation is for developers. We live in code, we like to read text. The current format has high information density and not too much embellishment/distraction. Great.

And that's why I was horrified by your screenshot example. Lars so beautifully illustrated the problem in red in his comment above. It's typical of the "mobile-i-fying" of websites that tends to be the rage. Almost nobody reads ABAP Documentation on their mobile, give us content.

If you want to update it, look at Eclipse help for inspiration:

Eclipse documentation format

I don't know what framework they use as I've seen the format elsewhere on the web, but for me it's simple and useful, very fast, with a search that works, and it doesn't need loading while clicking through the tree, focus is on content, perfect!

On a tangential topic, here's an article for UX geeks: The Negative Impact of Mobile-First Web Design on Desktop

The search desperately needs improvement, but that goes for pretty much all of SAP documentation. This is where effort should be focused IMHO.

Jelena · ‎10-26-2023

+1 on everything.

I know what you're talking about on C but this may have been fixed, at least in some versions. Haven't seen that issue in a while. In any case, it's important that it doesn't get broken again.

Jelena · ‎10-26-2023

To pile up more stuff on top, please try to read the documentation from a POV of someone who is new to ABAP. SHIFT command is a great (or rather bad 🙂 ) example. This is how it starts:

SHIFT dobj [ {[ places][ direction]} | deleting ]

Effect

This statement shifts the content of a variable dobj. In places, the number of places to be shifted can be specified and in direction, the direction of the shift.

After reading this, my first thought is "What are you talking about?! What dobj / shmobj? Can't you just give me an example?!". An example appears later on and, again, it's not a good one. To get an example for places or direction you have to navigate to different part of documentation. This is probably logical from the content management point but it's not great for consumption. What it could be instead is something like this:

" These commands will shift content of my_variable left by 2 places

SHIFT my_variable BY 2 PLACES.

SHIFT my_variable LEFT BY 2 PLACES.



" This command will shift content of my_variable right by 3 places

SHIFT my_variable RIGHT BY 3 PLACES.

I think it's a great advantage of ABAP that it reads like plain language (except for some new syntax, ugh), so it's actually very easy to explain something with a simple example. And more detailed text can be there if anyone needs it.

By the way, some people already started creating something like Z documentation. I think the intent is admirable and I get why someone would do it (out of desperation). But at the same time it's a slippery slope. Is this repo going to be updated or will become a misleading ghost town?

It'd be great if this was not needed and instead there would be more collaboration between SAP and community to create good ABAP documentation centrally for everyone to use.

Jelena · ‎10-26-2023

I think it fulfills request number two just fine but misses the mark on point one. By now I've made my peace with ABAP documentation but the feedback we received from new learners is that they pretty much cannot make any sense of it. They're coming from non-SAP development background and are used to working with documentation for other languages. And here is where ABAP documentation doesn't compare favorably. Please also see my comment below.

larshp · ‎10-27-2023

Let the users run the examples, no need to explain stuff, just see by doing,

lenapadeken · ‎10-27-2023

Hi Ethan,

Thanks for your suggestions!

The hamburger button in the upper left is indeed there to collapse the navigation. We may find a better place for it and make it more intuitive.

horst_keller · ‎10-28-2023

That's what we do since long in SAP GUI and the ICF-version and now also in ADT, see https://blogs.sap.com/2023/10/24/abap-console-reloaded/.

The ABAP Keyword Documentation offers hundreds of executable classes* and programs in package SABAPDEMOS that are explained in and are executable via F8, F9 and directly from documentation display in the system.

In SAP GUI, you can also open the embedded textual examples (not delivered as repository objects) via an icon in an example frame for execution in the ABAP Editor already. For the other display versions that are not connect directly to the backend we are planning a pseudo execution with result display.

*In order to become ABAP Cloud enabled, previous demo "reports" were migrated to F9-enabled classes.

horst_keller · ‎10-28-2023

Just to mention it, this "Z documentation" is brought by SAP itself to you 😉

https://blogs.sap.com/2022/12/06/abap-cheat-sheets/

The lamented problems of the ABAP Keyword Documentation are clear and discussed in the ABAP F1 Help team itself. Not too long ago we were still writing books to extend the system documentation, now new ways of publishing emerge ...

larshp · ‎10-28-2023

Thanks

I think its missing my point, there should be no need to download or install an ABAP system to be able to get knowledge of how ABAP works, or try it out. The ABAP help is the first entry point, it should be accessible to everyone, no need for 32+gb systems.

Plus, I don't think demo programs should be part of 100.000+ installations, SAP advocates to keep the core clean, there is a nice opportunity to keep customer systems clean, and examples updated by providing it via the internet.

Sandra_Rossi · ‎10-29-2023

Nice to add a reminder to this guide (I had forgotten it/forgotten to react at that time).

I'd still advocate for a non-SAP documentation, because of this restriction which looks like it's more one SAP employee initiative (or a few ones) than a SAP company long-term-supported initiative:

This is not intended to be a contribution repository, so please do not create pull requests. If you like to address issues or suggestions, please create an issue. However, this project is provided "as-is": there is no guarantee that raised issues will be answered or addressed in future releases.

I would allow the community to participate, propose pull requests as it's done with Clean ABAP.

I would also turn the ABAP cheat sheets into a user guide.

horst_keller · ‎10-29-2023

About: "The search desperately needs improvement, but that goes for pretty much all of SAP documentation. This is where effort should be focused IMHO."

Please be aware that the ABAP Keyword Documentation is an online documentation for ABAP Editors.

https://blogs.sap.com/2017/04/04/searching-the-abap-keyword-documentation/

If that doesn't work as expected, feel free to contact us by the mail address mentioned in the blog or open an incident.

The portal version is an additional goodie and only a rudimentary search is currently implemented.

https://blogs.sap.com/2017/09/21/abap-news-for-release-7.52-searching-the-abap-keyword-documentation...

With the new design, we are also planning to improve that considerably (e g. better analysis of the search index and iintroducing type ahead).

julieplummer20 · ‎10-30-2023

Hi Lena,

Can I just echo Jelena's first point?

If I google an ABAP command, too often the info appears without the Navigation Tree.

In most cases, I would prefer to see the Tree by default, but make it collapsible and/ or adjustable-width.

Also - which Jelena didn't say, this is just imv - I often want to open 2-3 docu pages - ie "Open in new tab." Could this be made possible in future?

Thanks, Julie.

vonglan · ‎11-01-2023

I like that a copy of the documentation is in every SAP system.

As it is text, I am confident that it uses up only a tiny amount of total system space.

lenapadeken · ‎11-02-2023

Hi Julie,

The "Open in new tab." is taken care of in the new version.

As for the Google indexing, that will be another issue we need to consider.

Jelena · ‎11-02-2023

I guess the community should just create our own "cheat sheets". With Black Jack and ... Well, you know how the quote goes. 🙂

larshp · ‎11-03-2023

Clean ABAP: it talks about the "community" but that community is one inside SAP. From my point of view its not open, there is a blog somewhere describing parts of the process

I565544 · ‎11-08-2023

Great job, thanks a lot! Looking forward to more of your sharing!

Mandar_Damle · ‎01-16-2024

Is it available for all? I still see the old view.

lenapadeken · ‎03-27-2024

Blog for the Web and Help Portal versions is now available: The ABAP Keyword Documentation gets a new design (part 3).