Technical Articles
Using Markdown to document ABAP code
Having worked in IT for about 17 years, mostly as a consultant, I’ve yet to see a company where the technical documentation is up-to-date and reliable. I think that a major reason for the documentation not being up-to-date is that documentation is maintained far away from the source code, for example in a plethora of Word documents stored in a separate Solution Manager system. In this post, I’ll explain how Markdown files being handled in a Git repository can bring the documentation much closer to the ABAP source code.
Markdown
In practically every SAP project I’ve worked on, Word has been the go-to document format. Being active on GitHub, I’ve lately often found myself editing Markdown files. I find Markdown much easier and quicker to write in. Searching through a large number of Markdown files in a Git repository is also far easier than trying to scan through a large number of Word documents stored in a document management system. Why wouldn’t we be able to use Markdown to document ABAP development?
Tools
We use Azure DevOps together with abapGit to version control our ABAP code. We decided to use the same tools to manage our technical documentation in Markdown format. My go-to editor for Markdown files is Visual Studio Code with a couple of Markdown-related extensions.
Work process
My work process typically looks like this when doing development and writing documentation:
- Do the development in the ABAP system.
- Use abapGit to create a new branch in the repository hosted on Azure DevOps by using the Transport to branch functionality of abapGit.
- Pull the branch to my local PC.
- Add the Markdown file to the branch in Azure DevOps by pushing through command-line Git.
- Create the pull request in Azure DevOps.
- The code change as well as the documentation is reviewed by a colleague simultaneously.
- Feedback from the code review might lead to pushing new changes in the code as well as in the documentation to the repository.
- The pull request eventually gets merged and the code, as well as the documentation, is updated in the master branch.
Level of documentation
Typically we create one Markdown file per package and name the files in accordance with the packages they document. As an example, when creating a Markdown file documenting a package related to activities named ZACTIVITY,
the Markdown file should be put in the package folder (e.g. src/zactivity/) and should be named zactivity.md. Note that it is important that the filename is lower-case since abapGit otherwise will throw the error described in the following issue for example when adding the file to the ignore tag in file .abapgit.xml.
In general, the code should be self-explanatory, and not require extensive documentation through comments or Markdown files. The Markdown documentation should give another developer not familiar with the package an overview of the package, for example describing in which process the code is used and what problem it solves. We typically try to document important design decisions that were made when writing the code as well as highlight design patterns used. If there are dependencies to other packages these are also described. We try to keep the documentation brief and view it as something that should point the reader in the right direction, rather than explain every implementation detail extensively. To help the developers write consistent documentation we’ve created a Markdown template with headlines and hints of what might be relevant to include in the documentation.
Searching the documentation
Structurally the documentation is easy to find since it is maintained in close proximity to the code. In Azure DevOps it is also convenient to search through the whole repository or across several repositories. The search can be limited to only include Markdown files by using the criteria ext:md in the search box.
Conclusion
I think that using Markdown files in combination with a Git-managed repository gives excellent results in keeping the documentation alive. The documentation lives very close to the code and is easy to find, maintain, and review.
Happy documenting!
This blog post first appeared on the Developer Voyage blog at https://www.developervoyage.com/2020/12/19/using-markdown-to-document-abap-code.html
Good blog! I've read a lot of documentaries in my work life and none was really up to date. Some of them had a good structure, which is how I came to arc42. The mistake was always that documentation was written in Word and stored in a different system than SAP ERP.
What happend? Broken link! Moreover, most Word users unfortunately cannot use the strengths of Word at all. Then why not use Markdown right away? Fewer options, but learned faster. It can be written with any simple text editor. You don't even want to talk about the comprehensive integration in GitHub 🙂
In addition, I believe that in the future it will be necessary to be able to generate more documentation automatically at any time based on the development objects. Only the actual development objects are up to date. In this context I would like to look at projects such as "ABAP to PlantUML".
For all German-speaking readers: I once published an article on the topic of documentation on heise Developer: "Of Pyramids and Documentation".
Thanks! I agree with your point that in the end only the actual development objects are up to date and the source of truth.
I'd recommend naming the package documentation
readme.md, because this file will be rendered automatically if it is found. You can do this in each subfolder, not just the repository root!I also recommend the draw.io plugin for vscode, through which you can create svg diagrams, embed them in markdown and edit everything from the same place, with previews.
Thanks! The draw.io integration is very neat! Other plugins I use are: