Documentation: The Castor Oil of Programming

Ideally, all code should be self-documenting but there are many cases when documentation in human language is still needed, such as in API development.

Late Gerald Weinberg, the prize-winning book author called documentation “the castor oil of programming”: good for you but programmers hate it. Personally, I don’t mind writing documentation, but for the majority of programmers it’s nothing but a manager-pleasing chore. And even if a documentation gets written, it is frequently useless (copy-pasted code and screenshot galore, y’all know what I’m talking about), far removed from the code itself, and rarely updated.

SAP recognizes this and starting from ABAP 7.4, we can use the tool called ABAP Doc (the idea borrowed from Javadoc). And with wider adoption of abapGit, other git-based tools, such as Markdown, can be used by ABAPers as well.

When it comes to SAP itself, documentation is a two-headed beast: there is technical documentation (such as BAPI / API interfaces) and SAP Help. In the technical documentation department, there have been drastic improvements in the recent years, with SAP API Business Hub being nothing short of amazing, compared to the BAPI documentation. But SAP Help traditionally has been rather unhelpful and even inaccurate. Not only that, but the only feedback options for the customers and various SAP mercenaries were either screaming on social media or submitting an incident via well-guarded SAP Support channels.

Surprisingly, SAP finally recognized that as well and is now embarking on the Open Documentation journey. As a pilot, SAP is “opening up” SAP BTP documentation where anyone with a GitHub account can chime in. I say this is a great start and I hope this initiative moves forward much faster than the SAP BTP Free Tier saga. JP

Don’t miss our latest issue!