Skip to Content
Technical Articles
Author's profile photo Michael Keller

ADT, ABAP Doc, abapGit, GitHub, Markdown, mermaid

Dear community, the title of this blog sounds like buzzword bingo, but it isn’t. The technologies that these terms represent can be used in combination to keep track of things in everyday developer work. How? That’s what this blog is about.

At the moment the whole thing is still research, trying out and gaining experience. Please feel free to share your experiences.

ABAP Development Tools

ABAP Development Tools (ADT) is the development environment for ABAP recommended by SAP. You can use it to develop for on-premises, but especially for cloud systems such as the Business Technology Platform (BTP).

From the beginning, the ADT relied heavily on text-based working with development artifacts. The ABAP Workench and other transactions in the SAP GUI, on the other hand, often rely on form-based working with development artifacts.

As an example, the creation of a function module can be compared. The interface is plain text in the ADT, in the ABAP Workbench there are different tabs for IMPORTING, EXPORTING, CHANGING, TABLES and EXCEPTIONS.

Both approaches, text-based and form-based editing, have their strengths and weaknesses. It took me some time to get used to text-based editing πŸ™„ Meanwhile, I find the idea “everything is text” very nice. But that may also be because I’ve become a big fan of Markdown.

Regardless, for our example here, the ADT as development environment is the method of choice.


The ABAP Doc documentation has a nice definition of what ABAP Doc is:

“ABAP Doc allows declarations in ABAP programs to be documented, based on special ABAP Doc comments. ABAP development environments that support ABAP Doc, such as ABAP Development Tools (ADT), analyze the content of ABAP Doc comments, convert it to HTML and display it appropriately.

This is a great chance to make development artifacts easier to understand with comments that are also specially handled by our development environment ADT. Just take a look at the ABAP Doc documentation to see what is possible.

I can only recommend using ABAP Doc sparingly and purposefully. Otherwise there is a confusing mix of ABAP Doc comments and ABAP instructions.

The knowledge should result from the design of the development artifacts and their interaction. Please note the recommendations from Clean ABAP style guide.

Below are two very simple examples of ABAP Doc comments that describes classes:

"! Class to represent a building as an object.
"! Class to represent a room as an object.

If you create an object of these classes and use the element information (F2 key) on the object, you get for example this documentation:

abapGit and GitHub

abapGit allows us to use the strengths of Git in the ABAP world as well. In particular, we can transfer our development artifacts from the repository of the respective SAP system (SAP ERP, SAP BTP and so on) to a central repository, for example on GitHub. This brings us much closer to the idea of an independent, decentralized, non-linear and temporally decoupled development.

At this point I would like to say thanks to developers like Lars Hvam and Christian Guenter and all the not mentioned but not forgotten ABAP developers who made abapGit possible and thus provided one of the essential foundations for open source to flourish in the ABAP environment πŸ™.

Back to the example: The ZMKE_CL_BUILDING class shown above is a development artifact. If it is transferred to a repository on GitHub with abapGit, its source code can be found (and edited) there. So also the included ABAP Doc comments.

Markdown on GitHub

Wikipedia’s definition puts it beautifully: “Markdown is a lightweight markup language for creating formatted text using a plain-text editor“. GitHub offers us an incredible number of helpful documentation options within our repository via Markdown.

Simply create *.md files as is and follows the thought “everything is text”. After editing, which is possible directly on GitHub, GitHub takes care of the visually appealing preparation in HTML.

So here’s a link for learning Markdown and check this link and this one to see how GitHub make use of Markdown.


Here’s the definition of mermaid from their website: “Mermaid lets you create diagrams and visualizations using text and code. It is a Javascript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

With mermaid we can, for example, create class diagrams using a syntax easy as Markdown is. Even better: GitHub supports exactly that and prepares such a class diagram optically and in place.

Here’s our example as very simple mermaid class diagram on GitHub in plain text:

    class ZMKE_CL_ROOM{
    click ZMKE_CL_BUILDING href "" 
    click ZMKE_CL_ROOM href ""

And here’s the output, rendered by GitHub:

It’s interesting that you can set a link for each class, linking on files in your repository or somewhere else. So it can refer directly to the appropriate file with the source code of the class, for example. This allows you to look at the class diagram and jump into the appropriate source code on GitHub.

For that reason, I wouldn’t put much effort into the class diagram at first. It’s only intended to show the connections. By linking to the development artifacts, you can reach them easily and look at the details there. As a side note, the link path should be relative to the repository. But I haven’t gotten that resolved yet.


By using ABAP Doc, for example for a brief description of classes, in connection with the ADT, a simple but easily accessible documentation can be created. If you make the documented development artifacts available on GitHub and create a simple mermaid class diagram, it’s easy for other developers to get started with your source code because they have a fast overview. Even withouth access to a SAP development system.

Automatic generation of the mermaid class diagram on a commit would of course be ideal, or at least one could generate a class diagram in the ADT.


Thanks for reading, stay healthy and kind regards



Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Lars Hvam
      Lars Hvam

      Update the code and documentation via the same process and system, that works.

      Also suggest taking a look at AsciiDocΒ for larger more organized documentation, its functionality is somewhere between markdown and LaTeX

      For UML diagrams and abapGit, there are always up to date diagrams available, example ZCL_ABAPGIT_CODE_INSPECTOR

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      I've also worked with AsciiDoc and that was great too. Highly recommended. Getting started with Markdown and AsciiDoc is a nice change in everyday developer life.

      Author's profile photo Joachim Rees
      Joachim Rees

      Thanks for the Tipp! I learned to love Markdown a few years ago, and AsciiDoc looks very nice, too!

      Author's profile photo Andrea Borgia
      Andrea Borgia

      Considering that I'm still trying to find the right balance, I have to say that I tend to use ABAP Doc and normal comments for two distinct reasons: for variables, methods and such then ABAP Doc because it is extremely convenient in Eclipse; when it is a general comment, for example to describe the context or functionality of a specific code block, then normal comments.

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      Agreed. I do the same. Although I actually need ABAP Doc for all classes, the name of the method is sometimes enough to explain it. If only there wasn't this 30 character limit for method names...

      Author's profile photo Jelena Perfiljeva
      Jelena Perfiljeva

      Thanks for sharing, Michael! Good note on ABAP Doc, it can easily get over-used.

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      If used incorrectly, the source code will look dirty (code smell?). Like a garden where one bad plant has taken over πŸ˜‰

      Author's profile photo Ryan Fleischmann
      Ryan Fleischmann

      Great overview.

      I've really liked how gitbook formats API documentation. One thing I'd love to see is Abap Doc + Abap Git bootstrapping something into Gitbook. It makes sense for inline documentation to have brevity - and use another tool like Gitbook for in depth explanation of functionality.


      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      Sounds interesting. Here's a link for everyone interested what GitBook is. There's a free offer for open source projects. Looks a little bit like the GitHub price model.

      Author's profile photo Syambabu Allu
      Syambabu Allu

      Hi Michael,

      Great blog..Thanks for sharing in detail!!

      Thank you,


      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      Hi Syambabu, thanks for your kind words. After a lot of years, I still believe in the power of sharing and discussing knowledge and experiences in communities. According to your SAP Community profile, you feel the same way πŸ™‚ Have fun and success with people and technology!