The german SAP user group (DSAG) offers a readable and also free guide called "BEST PRACTICE GUIDELINES FOR DEVELOPMENT - USEFUL TIPS FOR ABAP DEVELOPMENT". The guide is available in English and German.
The guide mentioned arc42 as a template to document and communicate software architectures. It's a free template based on the experiences of the authors Peter Hruschka and Gernot Starke in the field of software development. Nice fact by the way: The number 42 in the name is an allusion to Deep Thought's answer in "The Hitchhiker's Guide to the Galaxy" 😉 The template is structured in 12 main chapters that cover various topics. These include technical, functional, organizational and qualitative topics that play a role during software development.
I've worked with the template in a few projects and what should I say? I like it. If documentation is necessary, arc42 offers a great solution. Here are some notes about my experiences for those who are interested in (even if you don't want to use it, you may be able to use an idea from it for your own documentation template).
Quick overview of pros and cons
Here is a quick overview of the advantages and disadvantages based on my experience.
available for free in different formats like Word and AsciiDoc
structured and thus comprehensible
is constantly evolving
can be easily expanded with sub-chapters
filled in as required (not every chapter is mandatory)
is universal and therefore not dependent on a programming language
can be used early in a development project
addresses different audiences
available in English and German
training available (with costs)
reference books available (with costs)
effort to become familiar with the structure
effort to learn how to use it with the appropriate programming language (ABAP)
since not all chapters have to be filled, the document can seem little informative at first glance
too complex for micro projects
Not part of arc42
Incidentally, arc42 does not solve the following tasks. In my experience, however, these tasks aren't solved by any documentation template and can only be solved by a corresponding work organization.
keep documentation up to date
have enough time (budget) to document
create motivation to document
define storage location with an easy to understand structure
create high-quality documentation (depends on many factors)
improve communication between people working with documentation
link between the documentation and the development objects in the system
ensure quick availability
For those who are interested in the use of arc42, here are some sources for your first steps.
And here are some notes about my first steps ... there is so much to report that it would go beyond the scope of this blog 😉
Tools: For the simple and fast creation of an arc42 documentation, I recommend Microsoft Word and Visio as well as Greenshot (or any other screen grabber). However, a Word document can be difficult to coordinate when multiple people working on the same document without the use of a Microsoft Sharepoint. In this context, the arc42 templates for Confluence are interesting. So far, I couldn't experiment with that much but I think it's worth a look.
Starting point: After dealing with the mentioned sources, I started with a "simple" application based on an ALV Grid, which included some specials in the selection and data preparation, so that a documentation was useful. I can only recommend to first choose a small and simple project to start with arc42 and to use the documentation template with the help. The questions and notes in it raise enough additional questions and you are busy for a while. Nice colleagues to discuss the questions are also very helpful at this point 🙂
Text content: I tried to formulate short sentences with one thought at a time. Overall, only as much text as necessary and as little as possible. Since the document addresses different audiences in its various chapters, the use of functional (process) and technical terms automatically results. In the first few chapters this is more process orientated, then it becomes technical. In the chapters in which I had nothing to describe, I have indicated that by a note.
Visual content: As it's often the case for designing content, a picture is worth a thousand words. That's why using the Unified Modeling Language, screenshots and the graphic possibilities of Microsoft Visio can be very convenient.
Sharing Best Practice
At the moment I am learning a lot with every development that I document via arc42. For example, the chapter "runtime view" in my first documentation of an ALV-based application had little relevance and therefore no content.
On the other hand, when documenting a complex customer enhancement via Business Add-In ME_PROCESS_PO_CUST, it was great to make the interaction of the modules in the overall context of the standard application logic clear. As a developer, this is very helpful during debugging.
For me it becomes clear that only through different projects you can learn the different subtleties of an arc42 documentation.
Therefore, if someone is interested in exchanging ideas and contributing his experience to a kind of "ABAP arc42 Best Practice Guide" published for the SAP Community, please contact me.
Since there is an arc42 markdown template, this could be interesting for open source projects on GitHub. In this way, you can communicate the architecture of the respective open source project faster and thereby simplify the entry for other developers.
One last note
Finally, a general word regarding documentation. For me, the design of an application is already a form of documentation.
Those who try to respect principles like "Separation of concerns", naming conventions, design patterns, using quality comments and much more as best as possible make it easier for another developer to find his way through the source code jungle (check SAP Code Style Guides). Some development objects reveal much at the first glance 🙂
In case of doubt, there is no documentation or you can not find the existing documentation, then you are dependent on the development objects and can only hope that their purpose is self-explanatory 😉