As a software developer, you always need reliable documentation to guide your work. If you are like most software developers, you can be supporting multiple applications at the same time, which means that it is even more crucial to have software documentation in place to track all aspects of each application. It is also very helpful for development, maintenance and knowledge transfer to other developers.
During my career as a Software Developer, I have noticed that many software developers are conscious of the necessity of accurate software documentation but have a strong distaste for creating it. The act of taking screenshots and writing documentation seems to be a painful and time-consuming experience. Especially in regulated industries, such as pharmaceutical manufacturing and healthcare, having a detailed, gap-free documentation is an important prerequisite before going live with the custom developed application.
Why software developers should create technical software documentation
IT Compliance departments and auditors set the highest demands when it comes to software documentation. But also IT Managers should strictly follow up the delivery of correct and gap-free documentation after new software has been developed. After all, the knowledge about newly developed software should be made centrally available and should not be attached to individual persons. At all times, it should be avoided that this knowledge disappears together with someone leaving the organisation.
Internal documentation vs external documentation
SAP provides a way to document Dictionary Objects directly into the system. With this feature, however, only so-called internal documentation can be created. To have all relevant information in one place, all this system-internally documented information needs to be rewritten in so-called external documentation in e.g. a Microsoft Word document. Most SAP ABAP developers I asked, want to avoid these double efforts and therefore only create documentation either within SAP or in an external Microsoft Word document. In a third scenario, they don’t create any documentation at all!
The risks of not creating software documentation
Please bear in mind that avoiding creating software documentation involves big risks for your organisation with regards to maintainability, quality management, knowledge transfer and further development of the software application. Without software documentation, your software developers cannot keep track of all aspects of the application and may be forced to “re-invent the wheel” at a certain stage. If you recognise this at your organisation, I recommend you to continue reading this article to learn which steps you can take to eliminate these risks.
Why you need both internal documentation and external documentation
In case a new developed software application has gone live without any technical documentation, it is very hard for someone else to get an understanding of the technical aspects and logic of this application. In this scenario, you cannot expect to harvest possible benefits of maintainability and higher quality. However, if you want to unravel the technical mysteries, you need to go through a complex process of reverse engineering, which is basically only an attempt to understand the required (business) logic, based on the technical implementation. For complex programmes, you need to put so much effort in this process that it may be cheaper and more efficient to completely redevelop the logic from scratch.
In a second scenario, where the documentation is only available in the system, it is very difficult for an external party, such as an auditor, to get a quick overview of the main components and purposes of the software programme. To avoid this, many organisations require external documentation being made centrally available.
The third scenario implies only having external documentation in e.g. a Microsoft Word document. This offers a good way to gain a quick overview and understanding of the programme. Nevertheless, when another developer needs to work with a piece of the developed code, having an internal documentation is crucial. This provides details about the architecture and design of each piece of the code and enables the developers to quickly analyse the available code and pick it up at any time.
My recommended approach for creating software documentation
In my experience, the ideal scenario to avoid any risks and to work as efficiently as possible is creating internal documentation that will also be recorded in centrally available external documentation. For this reason, I developed the SAP ABAP Documentation Generator together with my colleague, Jörg Hofmann. This tool automatically creates technical documentation for SAP ABAP and SAP ABAP OO developments.
How the SAP ABAP Documentation Generator quickly creates software documentation
When using the SAP ABAP Documentation Generator, you start by selecting a complete development package, a transport order or individual objects. Next, the tool will identify all repository objects that belong to this developed code and allows you to choose which object types are to be documented. In the next step, an inventory of all objects is created and exported into an editable Microsoft Word or Microsoft Word XML document.
Creating this kind of documentation manually would take you one/two man-days. The SAP ABAP Documentation Generator performs this job in only 2 minutes!
Thanks to the SAP ABAP Documentation Generator, the SAP long text documentation about the objects can be transferred into the generated Microsoft Word or Microsoft Word XML document as well. With this feature, a software developer saves a lot of time since he only needs to create the documentation once – directly in the SAP system. The external technical documentation can then be generated at the push of a button with the SAP ABAP Documentation Generator.
This guarantees both the internal and external documentation containing the same information and being centrally available. For comparison: creating this kind of documentation manually would take one/two man-days. The SAP ABAP Documentation Generator performs this job in only a few minutes.