ABAP Keyword Documentation - Tell us what you think

[horst_keller]

The ABAP Keyword Documentation is a special kind of SAP documentation that you normally see after using F1 in a source code editor of ADT or ABAP Workbench. ABAP Keyword Documentation is system documentation delivered with every AS ABAP, but you can find also copies in SAP Help Portal, where a "latest" version is always the most recent one: ABAP - Keyword Documentation (latest) is the same as ABAP - Keyword Documentation (7.57).

There, you will find the possibility to Mail Feedback now.

After offering that functionality inside SAP for a long time already, we are happy to announce a public mailbox f1_help@sap.com that you can reach directly from the documentation display and where the mail is prefilled with information about the current document:

In upcoming releases, this will be also offered in the backend based F1 help in the ADT and ABAP Workbench versions of the documentation in customer systems.

We invite you now to

• send us your opinion and comments about general documentation or special topics


• notify us about typos or other errors


• point out sections that are not understandable and need clarification


• send suggestions for hints and examples


• ...

But please note that this mailbox is neither a discussion forum nor a hotline address for the ABAP languages and tools. Its sole purpose is to improve the ABAP Keyword Documentation and adjust it to your needs. And please, mail responsibly. If we are getting spammed, we might remove the mailbox in no time.

Looking forward to hearing from you.

The ABAP F1 Help Team

 

 

 

 

 

[matt]

I like the initiative. But I fear the spammers....

Personally I think the F1 help documentation is very good. I just wish more people would read it!

I developer software in ABAP in 7.52, but it is shipped even to some customers on 7.31 (I know...) What I'd love to see is some indication of what release particular constructs came into being. A niche requirement, I'm well aware.

I'd also like to be able to specify the release when I syntax check - for the same reason. You can do this with Java.

Pipe dreams...

 

[abo]

On the same line of pipedreams, conditional includes dependent on version.

[horst_keller]

" What I'd love to see is some indication of what release particular constructs came into being. "

Indeed, we have a backlog item for that demand and we even created a database table with release tags for all indexed language elements already. We are still not clear about how to display this information in the documentation (mouse over or whatsoever).

 

[horst_keller]

I guess you mean "release" when you say  "version".

For ABAP language versions ("Standard ABAP" vs. "ABAP for Cloud Development") the documentation is in fact "filtered" for version dependent contents in several ways, conditional includes being one of them.

But why release dependent filtering? The documentation reflects the current release of the AS ABAP where it is available.

[abo]

At the moment there is no way to write a program that behaves differently depending on the ABAP version, so this does not work:

#if ABAP < 740

data: l_dummy type string.

l_dummy = 'Nice try'.

#else

data(l_dummy) = 'Nice try'.

#endif

(I'm not sure the cutoff is 7.40 but for the sake of the argument let's pretend it is so)

In pratice, this means that old code lingers around far longer than otherwise necessary, since it is the only way to have one unified codebase across all customers.

[horst_keller]

Ah, you didn't mean the documentation, but the ABAP compiler itself.

Well, see above "neither a discussion forum nor a hotline address for the ABAP languages and tools" 😉

[ChristianGünter]

I'd love to see ABAP Keyword Documentation as part of Open Documentation Initiative . Then improving the documentation would be just one pull request away.

[ChristianGünter]

I developer software in ABAP in 7.52, but it is shipped even to some customers on 7.31 (I know...) What I'd love to see is some indication of what release particular constructs came into being. A niche requirement, I'm well aware.

I'd also like to be able to specify the release when I syntax check - for the same reason.

I can highly second that. Imho it's not that niche.

[horst_keller]

Well, well. As said, ABAP Keyword Documentation is system documentation, written by a handful people in ITF-format and stored in database tables and the complete infrastructure is developed and maintained by the same people themselves. Most of SAP's "official" documentation guys even don't know about it. Your demand requires quite a change of that. In fact, from our point of view we surely might be able to feed the ABAP Keyword Documentation into such an Open Documentation GIT repository. But getting the changes back to the DB and keeping the Open Documentation GIT repository up-to-date with newly written documentation requires some effort.

[larshp]

Looking at syntax, write the code in high syntax, and then do automatic downport, https://blogs.sap.com/2022/07/26/storing-abap-build-artifacts-in-oci-registry/

Alternatively do automatic upport

 

[larshp]

in abapGit we already do this, most develop on 750+ systems, but the code is shipped to 702

Open a pull request, and the developer is reminded if the syntax is not 702 compatible, we will probably enable automatic suggestions(in the PR) for downporting

[abo]

I'm aware of that, Lars, but I'm new in my current company and it takes time to know the products and explore ways to improve them. That is on my radar, for sure!

[Marian_Zeis]

horst.keller

There is already some documentation on GitHub. It doesn't hurt to ask the other departments if they had the same problems and how they solved it.
Maybe there are already good solutions that you can use as a reference.

https://github.com/orgs/SAP-docs/repositories

[horst_keller]

Mainly DITACMS. Our documentation is (still) stored in DOKIL, DOKHL, DOKTL. I bet there aren't out-of-the-box solutions for that kind of documentation ...

[BaerbelWinkler]

Cool!

Just wondering how practical an approach getting feedback via email will be in the long run? For one - as I just noticed when clicking on the icon - my browser expects some email-setup but we don't have a typical mail client which springs into action automatically with such prompts (we are on Google Workspace).

For another on your end, you'll have to extract relevant information from the body of the email.

Wouldn't something like a Google-form, where you get feedback neatly arranged in a spreadsheet, be easier to handle? Just like with your prefilled email, you can generate a Google-form with some fields filled in based on the context it's linked from. And if anything Google is not an option, than I'm sure there are other comparable options available!

Cheers

Bärbel

[horst_keller]

Hi Bärbel,

If your rmail client does not work with the link, you can easily send a mail to the address given in the blog directly.

Well, yes, we'll see how far we get with this approach. If it turns out to be not feasible, we'll think about other ways.

Best,

Horst

[shais]

Open Chrome email links in Gmail

[marcfbe]

I find syntax diagrams that include the release dependencies like https://syntax.abaplint.org/ incredibly useful. Something like this with syntax parts linked to the corresponding doc would be great.

[marcfbe]

+1. It's not niche at all. The vast majority of custom and partner solutions span multiple releases (just like SAP code). Few are keen on maintaining several SAP-release-dependent versions of your solution. Therefore, one sticks with the lowest release that you need to support.

[marcfbe]

Hi Horst, why would you want to get it back into the outdated SAPscript format? Get rid of this format altogether! Get rid of all the DOKIL data that's wasting HANA memory. You can probably simplify transaction ABAPDOCU a lot, too since 99% of the time devs are just pressing F1 on a keyword.

We already have everything we need in HTML on https://help.sap.com/. That should be the starting point. Use an HTML to markdown converter. This markdown would be a beautiful foundation going forward.

It's a one-time effort. Outsource it.

Now, embed the HTML version into ADT. Add a proper search engine (the current one sucks).

ZIP is all up for companies who want or need it behind their own firewall. Actually, these companies could just clone the repo.

The more you think about it, the better this gets.

PS: For the 99% solution (F1 in GUI editor), just try this enhancement:

ABAP Docu Enhancement

PS: I know quite well that I'm simplifying and a real implementation takes much more effort. The point is to look at it from a different angle. 

[horst_keller]

That's about what we are planning. We consider relaunching the syntax diagrams of the short reference for that purpose,

[horst_keller]

We are looking at it from many different angles and we already started a refactoring that involves an intermediate XML format from which everything will be possible.

You say "99% of the time devs are just pressing F1 on a keyword." After F1, the documentation for the clicked language element is searched and an appropriate list of alternatives or a direct hit is opened. For that, the editors pass information about the clicked context to the keyword documentation's infrastructure that is analyzed there. Why do you say that the search engine "sucks". How would you do it better? 

[lenapadeken]

Hi Marc,

A few short statements:

• The ABAP Keyword Documentation is written in SAPscript.


• We convert ITF to HTML, so the HTML version you're referring to is "converted SAPscript".


• We've many versions, let alone cloud and on-premise.


• Which version of the documentation do you use? 7.50? If you've any suggestions regarding the search, feel free to drop us an email (see Horst's comment).

[matt]

Well, yes. That's why I didn't email the wish list and posted here! 🙂

[marcfbe]

XML is not something community users would edit. For metadata, ok, but the text itself should be separate (i.e. markdown).

Sure, the editor has to analyze and provide the context. But then pass that context to a help.sap.com (search) that does the rest.

My comment was referring to the search on help.sap.com (not in GUI):

See https://twitter.com/marcfbe/status/1587117957758402560 for an example. As a minimum, it should index the content of the pages, no?

[marcfbe]

Hi Lena,

I understand how it works today on the SAP side (been there 😉 ). My key feedback is that the HTML version is the best format for consuming docs. For maintaining, markdown has proven itself in many open source projects as well as SAPs Open Doc Initiative (IMHO). That's why I suggest a complete rethink of how you/we handle ABAP docs. As long as the single source of truth remains in an ABAP system - actually many systems, I doubt that there will be factors of improvement.

Regarding "search" see my tweet mentioned above. Happy to provide more examples, if you like.

Best,
Marc
​​​@marcfbe​

 

 

[horst_keller]

"XML is not something community users would edit"

-> you missed the word "intermediate". Our XML will serve as source for HTML, markdown and whatsoever.

"My comment was referring to the search on help.sap.com (not in GUI):"

-> Our main product is F1 help in the systems with a search engine provided in ABAP. The version on SAP GUI is simply an addendum and your switching from the full ABAP implementation to calling the additional service is quite astonishing. The search there doesn't claim to be a search engine but is some JS produced in spare time so to say. But even for that, we are on our way doing it better.

[former_member812204]

Hello Horst,

why release filtering is simple to answer.

You are supplier of an add-on. Your Abap Release is 7.50. But often customers use older releases for a long time ( i know actually from some with 7.02 ). Because sometimes an update causes a huge workload.

 

So there are several scenarios :

You have different versions of you add-on in your developement system. Or you have different add-ons you deliver, the newest in new syntax.

So you need to garuantee the compatibility. In fact that you can not have release depending code includes in abap you need to know how a syntax in older versions works.

 

Example :

 

" _tab_command_list[ name = im_command_name ]-obj_command->execute( ). " not on  7.40

ASSIGN _tab_command_list[ name = im_command_name ] TO 

 FIELD-SYMBOL(<str_tab_command_list>).


<str_tab_command_list>-obj_command->execute( ).

So to have an idea how a new syntax can be transformed in old syntax is a big help. Also for learning how to transform old to new.

 

Actually you can only check this by having systems on that release level you need. You make an test import an correct what has to be corrected.

 

Of course the luxuray feature would be a) to write code for several releases at one time b) to have a syntax check with choosable release level.

 

Kind regards,

 

Gabor Toldi