There are multiple ways for Development Object's documentation - which seems to be the most hated activities in a developer's life. Due to increasing complexity of an application and also increasing components, which is part of the object oriented paradigm, this situation is more and more unacceptable. In particular, if the developer follows the object oriented paradigm, he has to build much more development objects, each with much lower complexity. The most different fact in object oriented software development is, that objects are communicating with other objects by calling the recipients' methods. This communication is much less obvious than proceeding procedural coding, so it has to be documented. Neglecting this results into a very much higher effort in maintenance, particularly if this maintenance has to be done by an another developer. This document wants to describe, how development objects can be enriched with a documentation, namely inline in the SAP system itself, so nobody has to search in big, platform depending, widely ramified file system trees.

Basics

At first, we have to differ the visibility of a documentation, which impacts into the target audience, they address: The documentation of a report, a module pool or a data element is visible for end users, the documentation of function groups, tables, structures, domains and other development objects are addressed to developers, regarding to it's content.

Any end user documentation should show his perspective: Related to the business process and not very technically, the usage of the program, it's requirements and prerequisites as well as it's results should be described.

A developer documentation, on the other hand, are written for developers (uh!), so they have to be focussed on the "Big Picture" as well as on the technical details of the implementation. What does this object in which content, which communications and relations to other objects are important, and so on. Linking between documentations will be needed much more frequently.

Translations

Documentations in SAP are principally translatable, which is very important in a multi-language environment like SAP. That means, in table DOKHL a language related column is provided and results into different translation strategies for both documentation categories: end user documentations should be translated into all languages, the program could be started with. For developer documentations it's enough, to maintain the company's language and - if differs - in English.

Coding comments

Not translatable - which results into the recommendation to maintain them in English - but very important and a part of the developer documentation are coding comments, which should follow the rules of ABAP Doc and explain everysinglestatement, which is not obvious. This comments shouldn't explain, what this coding will do, this is said by the statements itself (that's why we code in ABAP and not in computer's language), but why and in which context it works as it does. Accompanied by all other information, which is not provided by the statement itself, this comments are a great support of the whole maintenance process. Repeating this comments or parts of it is not wrong principally, it can make sense - the commenting developer should realize, that another developer does not read the whole coding, but only a (very small) part of it.

" preparation

" check for existing partner roles

....

" preparation

" check for existing SMTP address for each partner

....

Documenting the first development object

Entering Documentation

To follow this document's content, you should create a report in your system, which does not need any coding. Documentation maintenance is available in menu Goto -> Documentation for each development object, if you are in it's change mode.

After that, you will see one of the following:

The classic editor shows more technical details	The Graphical PC-Editor may be more user-friendly

This is a virgin documentation of Report ZZ_DOCU in language English. For explanations of technical contexts, the setting "Graphical PC Editor" should be disabled, the screen reflects the structure TLINE. In fact, this is my preferred editor for documentations, I've never became a friend of the Graphical PC Editor, which you can see on the right.

Text header data

The header of this document (available via Goto -> Header) shows more technical details, we'll need later:

Text Header Popup

The text name is the same as the object, which is been documented, the Text Name of components are concatenations of their main object and the component, which both have the length of 30 characters. This results into a name

ZCL_TEST                      MY_METHOD

for method my_method in class zcl_test. If you want to know, how the documentation of method my_method is distinct from another for attribute my_method, have an eye for the Text ID, which represents the kind of development object, which is to be documented - in this case RE for "Report".

Table TDCLD contents all of this IDs, i. e. for classes, interfaces, their components, module pools, tables and many others.

The Text Object is constant for all documentations.

We'll need this information for linking documentations to each other, which will be described below. In particular, the semi-automatic generation of developer documentations from all development object documentations will use this.

The fields Style and Form are not relevant for now, because we can't change them.

Structure vs. layout

As mentioned above, we'll stay in the 80's and use the classic editor to see more technical details. On the left hand, there is a paragraph's format column, to the right the text content itself. F4 in the format column shows the available alternatives. At the first glance, we can see, that AS is the main standard format and U1, ..., U5 are to be used for Headlines (same as H1, ... in HTML - we'll find more similarities to HTML, later). The paragraphs explain the structure of the document, which has quite impacts to it's design, but although they ain't be used for design matters.

Paragraph formats

Same as in HTML, the paragraph formats do have impacts to the layout, but basically they're dealing with the text's structure, so the client has to decide all about layout and design. Paragraphs, which are longer than a row, do have a paragraph just in the first row:

AS  This is a row, which is longer than a row, which results into

    floating text.

AS  This is the next paragraph.

As mentioned above, F4 in the format column (alternatively Format -> Paragraph)

Character formats

Actually, the character formats are dealing with the text's structure as well as paragraph formats, but they are much more close to the layout (in fact, there are limited forms of text accentuations, "bold" in most cases). Similar to HTML, it's to be implemented in opening and closing tags:

AS  character formats like <ZH>bold</>, <ZK>italic</> or <ZU>underlined</> and much more....

Symbolic

The headlines, which are included in a virgin documentation, are depending on form, style and application and do reflect the recommended structure of the document itself. Your company may define a different structure, just for it, but nevertheless, there has to be a standard, because standards ease the consumption of those contents.

Providing content is the core of a documentation, which is made to be read as easy and fast as possible. That means: The content has to be on focus and the structure of the document has to support and ease it's consumption, it's not a playground for mistaken eruptions of creativity.

As you can see in both editor screenshots, some expressions, included in ampersands, are shown in the headlines. Formular developers will know them, this are variables. In this case, they are implemented into the text to ensure translation of this headlines. This also means: If you use custom headlines, you have to translate them by yourself.

For company specific standards definition, system symbols should be preferred due to translation matters.

Icon "Preview"

If you take the bait of premature document visit, you gonna be kind of disappointed, because your document is empty. The reason is: Headlines without any content are not displayed (which makes sense, they suggest missing content, where content is just unwanted but not missed). To see, how the headlines are translated in your language and how it's format is been implemented, you can type any content (perhaps just an 'x') into each row with format "AS".

This was the first "Ah!"-Effekt for me, because what I saw was the same layout I knew from all SAP's own development object's documentations. As you are used to write ABAP coding, which does not differ conceptionally from SAP's ABAP coding, the documentation adopts the optical impression, the user knows. Seamless integration between standard and custom objects. Integration as its best.

Of course, this symbols can be used not only for headlines, but in the text itself, explore the items of Insert -> Symbols for more details, which symbols are available and which meaning they have.

Iconic

Even though you can use icons in SAPscript texts, you won't be able to print them (I didn't find any way to do that, to be exact). But because printing is too much 80's, we'll ignore that and use them. In fact, that is the easiest way to explain toolbar button features. Icons can be included by writing it's shortcode @...@ into the text. A list of all icons's shortcodes can be retrieved by starting the SAP standard report RSTXICON. Example:

AS  Here, for example, are the icons for minus @05@ and plus @04@ in a text

Setting links in SAPscript texts

Again, there is another similarity to HTML - SAPscript texts can be linked to each other. In particular, documentations are linked automatically (i. e. the parameters of a function module are linked to the FM's documentation). A link in SAPscript has the following syntax:

<DS:ID.TEXTNAME>highlighted text</>

As you can see, the link even looks analogically, compared with HTML links. DS is the abbrevation for the character coding, ID is the well known Text-ID, text name is (not surprisingly) the name of the text we want to refer to and like all tags it will be closed by </>. This means, a report's documentation of program ztest in the words "test link" looks like <DS:RE.ZTEST>test link</>. As explained above, table TDCLD contents all IDs, usable for links.

Additionally, you can create a link to a transaction like this:

<DS:TRAN.SE38>go to SE38</>

Internet Links are implemented by SAP, as well - there is only one TDCLD entry missing, which is described in Enno Wullfs Tricktresor (German only, but all other people can figure out the very short field mapping description)

Text modularization

One aspect of easy and fast documentation consumption, combined with error minimization is modularization. Text modules should be used for repeated text components, i. e. user help desk / SAP competence center contact data, links to a knowledge base (MediaWiki, Confluence, etc.) or a ticket system, which provides fast and complete failure notice, preferably under the headline &FURTHER_SOURCES_OF_INF&, which can be appended to each text. And - of course - if there are standards vor variable names in your company, i. e. E_RETURN will always the same documentation, because it always contains messages of the same structure.

Text modules are to be maintained in SE61 (General Text) and may included with the command

/: INCLUDE {textname} OBJECT DOKU ID TX

in which the "/:" is the content of the format column, the TX points to the fact, that this is a general text and not a documentation for a specific development object. Of course, it's possible, to include a class or report documentation for instance, as well.

This statement brings us to a solution to minimize the effort of writing a development documentation by creating a central document and chain all relevant development object documentations in one central document. Therefore, the development object's documentation should be divided in a part, which is part of the development documentation (which has to be a text module) and a part, which is NOT part of the development documentation (which can be written directly into the object documentation).

Advanced documentation techniques

A professional developer team, which regularly maintains documentations, needs some help to improve the level of documentation in form and content.

Table documentation in SM30

Enno Wulf describes in twoarticles in his Tricktresor (German only, sorry), how a table documentation can be shown in a table maintenance transaction. It's a mystery, why SAP did not implement that as a standard feature (in particular, this may be motivating for developers, to maintain these documentations). Of course, here could be a differentiation between a documentation for users on the one hand and for developers on the other hand.

I am using a similar technique to show text modules (created with SE61) in the same way.

Standard button for developer documentations

Again, this is a feature, which could be a nice standard feature for all programs: An additional toolbar button for entering the developer's documentation (ideally unshown for users without developer authorizations on this machine). This is one of my own best practices, I use ICON_SYSTEM_EXTENDED_HELP (@5E@), which refers to a general text, chaining all development object's documentations, as described above, and additional explanation text modules.

Documentation quality management

A periodical report can help to optimize the quality of this documentations or text modules. This is not as difficult as it sounds, it should read DOKHL in customer's namespace and get via FM DOKU_GET all relevant documentation headers, which results in a well known tline-based table for each maintained documentation. Possible checks could be:

• Syntax checks
• checks for and automatic inserts of mandatory contents
• checks for missing documentations
• checks for missing text modules
  

Finally, with FM DOKU_UPDATE the modified documentation can be saved.

Documentation to the future

The question may be, if this kind of documentation has a future, when the SAPGUI's end of life could be seen at the horizon, perhaps nearer. It has, because all documentation parts are accessible for a developer, so a migration to a new generation of documentation platform is possible. Candidates are: MediaWiki based Knowledge Base and Jira Confluence.

Appendix

Further information

• Official SAPscript Documentation
• SAP Print Doku: Word Processing in the SAPscript Editor

Request for comments

You are missing some content in this documentation? Is an explanation not written properly to understand? You found a wrong description or explanation? Just drop a comment, I'll be interested in improving this document.

Disclaimer: English ain't my mother tongue - Although I do my very best, some things maybe unclear, mistakable or ambiguous by accident. In this case, I am open to improve my English by getting suggestions