Stop writing Technical Documentation nobody will ever read

[Former Member]

If you're an ABAP developer, answer me: how many times do you really read the technical documentation of a Z program you're about to change? And for the times you did read the documentation, answer these: was it of any help in understanding what the code is doing? Was the documentation up to date with the source code?

In this blog, I'll try to tell you why I think we should get rid of poorly created Technical Documentation (I'll refer to them as "TDs" in this article), and change to a better approach. Many projects I've been in the past can SHIFT+DEL ALL of their TDs, and nobody would ever notice. Here's why.

------------------------------------------------------------

TDs with 10 pages for 500 lines of code

First of all, I hate documentation templates. I know why it was created in the first place, but most times that "old word template" is made by someone who knows nothing about code documentation.

Why do I have to add field name, description, type and length for every single field of a Z table I created inside a word document? Why do I have to specify all selection screen fields? Why do I have to copy things over from the Functional Specification?

Once upon a time I was in a project where we had to create a huge set of Z tables. Me and my ABAP friends had to write down in a word document every single field, description, data type, length, data elements, domains, etc, for every table we created. A huge amount of time lost writing a document that will be out of date as soon as a small field description is changed. And if we missed something, a reviewer would blame us for making poor documentation.

Due to those crazy and stupid templates, we end up having small source codes for simple processes with huge documentations. Documentations nobody ever care to read.

Coding ABAP in a Word Document

This one is classical. Some ABAP developers just don't care at all about code documentation. They don't write comments in the source code, and whenever they get a change they open a new word document, copy-paste the abap code from se80, name the file "SD.001 - My Program - TD" or something and consider they development is finished.

CTRL+C CTRL+V from ABAP to a Word Document.... JUST DON'T. It would be better if those guys doesn't even started making the "filler" file. The funny fact about it is that some reviewers consider this outrageous thing as something completely "legal".

It's all about the package: The project want to have the TD file; it doesn't matter if it's a piece of garbage. And I've seen a "CMMI level 5" software factory doing that. Way to go buddies...

Creating a DUOBM (Document Understandable Only By Me)

Ok, so the guy doesn't have to follow a stupid template, nor intend to make it a carbon copy of se80. But guess what: he also doesn't care about explaining to another developer how his code works.

The whole point about having a software documentation is so other developers can understand the software. If one fail in writing a good documentation he's also failing in delivering useful information about his creation. That development is a great candidate to become an "old and ugly Z monster nobody knows what is doing".

One of my favorite SAP technical documents of all time is the explanation of the good old iXML library. Take a look at this: http://help.sap.com/saphelp_nwpi71/helpdata/de/86/8280c012d511d5991b00508b6b8b11/content.htm . It's fun to read, it's well organized, and the writer knows he's explaining things to another developer. That's a major issue with software documentation in SAP projects: almost nobody cares about who's coming next. Let's just deliver everything until Go Live, make a Happy Hour and move to new projects. G-R-E-A-T.

------------------------------------------------------------

See? These are things me and my ABAP friends faced tons of times in Brazilian and International projects. Many gigabytes of word documents created because the project methodology said they must exist before software can pass through the homologation process. A sad truth.

Hopefully now you're not thinking I'm nuts by saying we should get rid of those documents. But don't get me wrong: I do like the idea of having a document explaining the software. Maybe not in the form of an word file: it can be an document created inside the SAP system, some entry in a CMS or even a small HTML file created with ASCIIDOC . But I strongly think we should be making things differently.

Therefore, I know a couple of things that can help making software documentation a relevant piece of information. Turns out they are very simple things people tend to ignore.

------------------------------------------------------------

What would you like to read in a Technical Documentation?

Get in front of a mirror and ask yourself: What you like to read in a TD? A lot of technical junk you could easily find by going to the relevant transactions, or something that helps you understanding the technical approach of that code?

Why you choose to add parallelism? Why did you have to use that complex recursive logic? A call transaction over a BAPI for VA02... why did you choose to do that? How your objects communicate with each other? Why that small functional process described in the functional specification turned out to be 5000 lines of code?

Answer questions like these on your TDs. Your ABAP colleagues will thank you for that.

Don't get too much "techy"

This may sound odd at first: if we're doing the Technical Documentation, why can't we go deep down into technical stuff? Because you should explain these things using comments. I've seen a lot of TDs trying to explain small little pieces of coding techniques inside the documentation, but I strongly believe these are things that should have been added as comments in the source code.

Example: "no read binary search on table X - can't sort it with this key because of <something>". That has much more value as a commentary instead of going inside the TD. People forget that comments are also a way of documenting what you're doing. Most times when we're trying to correct a small issue, we go directly to the debug screen, trying to solve the issue. Small and relevant comments can be extremely helpful in those situations.

Oh, and I'm yet to see a developer asking for the TD when his boss starts screaming on him about a bug in an old production code...

If you can't drop the template... what about a new one?

Technical Documentation templates were probably created by someone that though those were the relevant information they would like to see in the future. But sometimes those people are not experienced developers, so how can they know what really has to be in there?

If you're in a place where you can't stop using a "closed" template, make suggestions to remove the useless stuff and add some guidelines to help others adding value to that document. I bet you managers and leaders will change if it's for the best.

I had the experience of completing changing a project template once, and everybody loved. Even a functional consultant friend of mine was always saying about how he could read my TDs to help him understanding the programs from a technical perspective.  "A functional consultant reading a TD"? Believe, it's true!

Start reading some TDs!

I didn't realize these tips out of nowhere. When I was a very young ABAP n00b, I believed in unicorns, fairies, dragons and also in TDs. Yes, everytime I had a problem I tried to read the TD first, to see if it could give me a clue about the code. However, most times they failed miserable.

As time passed by I started debugging the code without reading anything at all. People wasted time doing TDs, but I didn't want to waste my time reading them.

It happens that old habits die hard, and even today I do like to take a sneak peak inside TDs. And yes, they've been the same in ABAP projects since 2006. I found cool documentations throughout these years, and they were the ones that opened up my eyes and made me change the way I wrote documentations.

Start reading some, and change too.

------------------------------------------------------------

I think that's everything I have to say about code documentation for now. I wrote about them in the past, but I thought this was a good time to raise the topic once more (this blog motivated me).

Please, share your experiences with ugly/cool documentations on the comments section. Let's debate and change this old "non-documentation" process.

Thanks very much for reading! :smile:

Best Regards,

Mauricio Cruz.

[Former Member]

Good one Cruz.

I started reading it thinking that I do have like minded people, not to concern to update the TD.

But towards the end, I was getting the importance to update the TD.

Most of the ABAP developers (of them I worked with) will not look and the TD at all for any changes in the code. I personally prepare the TD with the initial understanding on the program and God knows how many modifications are needed after the development of code. The update of TD will be ignored once the testing starts the it becomes outdated.

Generally a good developer will include all the important aspects as comments in the code.

Thanks,

Krishna Teja Peddada

[Former Member]

Hello Krishna,

I also like to add comments to explain small things inside the source code, but I fell the "big picture" has to be explained on another place.

Thanks for commenting!

[bruno_moreira]

Beleza Maurício,

imagino que seja brasileiro, portanto escreverei em português:

Até que enfim eu encontrei alguém que pensa exatamente como eu, verdadeira perda de tempo, pode-se escrever receita de cupcake numa ET e ninguém nunca perceberá, tenho verdadeira aversão!

No máximo um documento falando como executar, como é a execução e o resultado esperado

Abraço

Bruno

[Former Member]

É, a situação é bem complicada. Mais ainda com esse bando de picareta que a gente encontra por aí... Mas você me deu uma boa idéia, vou testar colocar uma receita de macarrão em um ET qualquer dia haha.

Abraços e obrigado pelo comentário! :smile:

[retired_member]

Thank so much!

I stop writing that dang technical ABAP Keyword Documentation immediatly and go swimming ...

:wink:

[SuhaSaha]

Horst Keller wrote:

I stop writing that dang technical ABAP Keyword Documentation

                   

Please think about the "mortal" developers who refer to the F1 help day-in & day-out before doing so :razz:

[SuhaSaha]

Hello Mauricio,

I could not agree more. I tend to keep my TS concise & to the point, i put the details on a need-to-provide basis. :wink: (I know very few ABAPers will refer to the TS when making a change)

I put more emphasis on the comments in the code itself, as you have said - "commentaries" in the code.

On more thing i try to do is create the documentation for a complex procedure (Function, method et al). I have the habit of checking the method/function documentation before using it, hence i prefer that i do it as well in my code for future reference :cool:

Cheers,

Suhas

[ThomasZloch]

From a support and maintenance stand-point - usually the longest period of a program's lifetime - I sure appreciate a good technical documentation, especially when I need to understand quickly what somebody else created.

It should describe the background and rationale, dependencies, overall architecture, process/program flows and the important ingredients. Extended 1:1 copies of table structures or program code is a waste of time and space, any developer can look this up in SE80.

Such document can be quickly created from a good technical specification, if there is any, but should certainly be created latest when the development goes into production.

Thomas

[Former Member]

If you keep writing only what matters, I'm sure you'll have a lot of time to swim :smile:

[Former Member]

Hello Suhas!

I'm also used to check functions/methods/frameworks/libraries/whatever documentations before using them. That's usually inside the system itself (through the documentation button or F1), and that's a awesome place to keep our own code documentation.

Best Regards,

Mauricio Cruz

[Former Member]

Hello Thomas!

You got straight to the point: we want important things, not pages and pages of useless info.

I also agree that if the TS is good, the final documentation has a better chance of turning into a good technical doc.

Best Regards!

[Former Member]

Hi Mauricio,

I don't have much experience like you although, still I want to share one thing. I am working in a manufacturing company in a support project from last few months, I have never made or referred to the TD yet.

My best friend "Debugger" has helped till now. Still, I feel that if I would have a precise document, I would have understood better and in short time. 

Regards

Purnand

[retired_member]

Alas, I have to write the complete reference, where you better scroll down to the examples in order to skip all the things that doesn't matter but have to be there for "legal" reasons. - swimming only sundays.

A compilation of things that really matter is another kind of documentation and might appear in form of tutorials, guides or books. Since this must be done in parallel to the real job - even less time for swimming ...

[Former Member]

Phew, at least people won't think I'm crazy by writing this blog. It seems TD are used even less than I expected.

Using TDs is also a matter of getting used to read documentations. Problem is that most of them are bad, and people never get the habit of referring to the TD once they start trying to figure out a Z program. And changing this "habit thing" takes time...

Thanks for commenting!

[Former Member]

Kinda sad that those "legal" reasons are keeping you away from pools... But I got a question about it: would see any benefit in changing those "legal reasons" in a way you could change the way you write the documentation, so you could swim a little more? (I'm asking this as I can't see no other way for Keyword Documentation than writing down every single possibility for each command...)

[kakshat]

Having read everyone's comments so far, I think what we all want to say is that we do need technical documents but that we want to take another look at what information we put into them. As already conveyed, information that is a 1:1 copy from the system [like copying the source code or table fields or messages from SE91 (yeah, I've seen that too!) or whatever] doesn't add much value and worse, leads to the additional task of keeping the information in the document in sync with that in the system. However, TDs, if written the right way, can help a person get the bigger picture in much less time than debugging. You can debug to understand a solution if there are a few objects involved but imagine a project that involves a horde of objects and you've just moved into the project. You would already start cursing the old developers. Yes, it's another story if the required information is already there in the design document but that's another classical debate as to how much detail you want to put into the design.

[Former Member]

One of the biggest problems to me are those projects with dumb documentation templates, and developers who turn on their "automatic mode", and doesn't care about writing something useful, they just follow the template. So imagine a template requires to write everything from a table (which would be extremely easier to be viewed on se11) - that's where this whole mess starts.

Thanks for your comment.

Best Regards!

[retired_member]

see any benefit in changing those "legal reasons" in a way you could change the way you write the documentation, so you could swim a little more?

You answered it yourself

no other way for Keyword Documentation than writing down every single possibility for each command

Otherwise, we couldn't point to the documentation in order to answer hotline tickets "ABAP statement blah does not work" (that's the "legal" aspect I meant).

In fact I'm alpha-tester of the ABAP language team. I'm literally trying out "every single possibility for each command" (even those the developers havn't dreamt of), write it down and create the examples. Naturally, the documentation then needs some time to mature ...

[Former Member]

Hello Mauricio,

How many times did you have someone really read and validate the TS when delivered? I believe developers as everyone else are lazy and selfish and don't see the point to spend time to do a good TS knowing nobody will ever open it and therefore they think a copy-paste is enough of their time for that...

But when the IT team actually believe in Quality and take the time to check and validate the docs, and asking the developers to redo it when it's not good, the documentation becomes a lot more usable.

And that is not only a question of TS, but all documentation... I cannot count the number of time I had to seat with a the person who wrote a FS so he can explain the 15 rules implied by the 2 lines wrote in the doc...

The funny difference I saw is that when a lot of developers may actually wrote better TS with more experience, the best FS I had to review where written by junior Functional Consultant, the senior consultants believing their time did not worth to write detailed documentation and that the technical people could go and ask if they don't understand...

PS: it's my opinion regarding the people I have worked with and obviously does not apply to every consultant, a lot of Technical and Functional Consultant can do good documentation 🙂

PS2: I am lazy and selfish but I try to apply to me the rules I asked other to follow

[Former Member]

Hello Sebastien

You brought up a good topic:

The funny difference I saw is that when a lot of developers may actually wrote better TS with more experience, the best FS I had to review where written by junior Functional Consultant, the senior consultants believing their time did not worth to write detailed documentation and that the technical people could go and ask if they don't understand...

                   

I've seen things like that happen a lot of times...

And I also agree that some projects just doesn't care about quality at all, but even between those who care about quality, there's always bad reviewers who will let any garbage written in the TS go straight to project's repo.

Thanks for your comments!

[Former Member]

Hello Mauricio,

I just read your article and thought like it is or must be the forecast of writing ABAP code and documenting it.

A lot of problems, that you’ve described in your post, we did face earlier and sometimes even today.

It is a good example for us how to change our development teams working habits and ideology.

Thanks again

Laurynas Prikockis

[deependra_shekhawat3]

Mauricio ,

You are right that most of ABAPer doen't look or need TD but i am not agree. As an ABAPer i always feel good that i am giving descriptive code and Proper Technical spec to others (who will take care after me). Technical spec is a nice thing in itself that gives you strong functional/Technical understanding for a long time.

Thanks

Deependra Singh Shekhawat

[AbhishekV]

Really a good one Mauricio!

The worst part is when you need to write the code description in the TD especially
in case of huge programs,I feel that it is a sheer wastage of time as certainly no one
would ever care to read that huge description(and even if they do read it they would
never be able to comprehend it)!!They would rather prefer to debug the code in order to
get a better understanding.

Adding comments at appropriate places in code certainly helps much more anytime than wasting time and energy in preparing useless documents!

[Former Member]

Good post.

I could'nt agree more. Sometimes the TD writing methodology is just outdated and it needs to be changed to fit its purpose. On the other hand, when you are new to a project the total lack of TD is worse than any (poorly) written documentation. I'd prefer something to read at least.

Regards,

[bjorn-henrik_zink]

I believe a key to good comments and documentation is to state why and not what (read: more why and less what). The what can be found in the code, the why is the reason the code exists. I also like to put emphasis on what you cannot find in the system, for example flow diagrams and/or sequence diagrams among others.

Thanks for a good blog post!

[SuhaSaha]

I believe a key to good comments and documentation is to state why and not what (read: more why and less what).

You nailed it Bjorn :smile:

Most of the TS templates i have worked with deal in the whats & not the whys. That's why i try to put the whys in my code as comments e.g., in one of my code is even gave a reference to an SAP note :wink:

One thing i have seen is that the original TS is generally not modified (when a change is made). We create new documentation for the change, attach it to the support ticket w/o ever bothering about the existing TS. Thus the original TS dies a silent death :sad:

- Suhas

[Former Member]

Thanks for writing this article, Mauricio.  It has sparked allot of good conversation, not only here on this forum, but amongst my colleagues and I on my current project.

My background - I'm a Certifed SAP HANA Associate, current SAP BI/BW Developer/Architect, PM and former SAP Trainer / Technical Writer.  As such, it seems like much of what I've been asked to include in my documentation doesn't really "fit" in a Functional Spec, nor does it really "fit" in a Technical Spec.

An example from my current project  - we have rigid Functional Specification and Technical Specification templates.  These documents are numbered and correspond to numbered "Z-items" in the system. 

We know creating/reviewing/maintaining documentation is an arduous process.  As a result, the incentive has become to reduce the number of new development items (technical objects) because of the perceived "baggage" associated with documentation.  While we have achieved CMMI compliance because we have a fully documented system, this has been done at the expense of certain design alternatives.

Example: Enhancements to add new fields to an existing InfoCube could be performed by creating a new Transformation and DTP from another InfoProvider (more elegant design???), or the new field values can be populated in an End Routine within an existing Transformation/DTP.  (Basically, changing/adding new info to existing Functional and Technical Specs, or creating brand new ones and going through the entire document review/approval process) 

When using project-wide templates, what works well for documenting a Function Module doesn't necessarily work well for routine within a BW Transformation.

All that said, the biggest thing missing from many Functional Spec and Technical Spec templates (particularly those that are intensive of listing all the fields, technical names, domain, etc.) is the rationale for WHY a certain design decision was made. (This goes back to your point about What would you like to read in a Technical Document?)  A sentence or two embedded within comments in the code are nice, but they don't go far enough.  This is especially true for code that was developed during initial implementation, perhaps by implementation partners, but is now being review at some point in the future by the SAP customer during an upgrade/enhancement.

I think most of the people who read your article were nodding their heads, saying "Yes." to themselves as they read through it.  Sadly, I think it's a case where the PMO defines the documentation standards.  Those can be based upon contractual requirements, company policy/methodology, or "That's the way we've always done it."  Unfortunately, it seems as though those who will listen, can't help and those who can help, won't listen.

[Former Member]

I'ts a good think you are reading TDs, but most developers I've known only remember there's something called "Documentation" when the project asks him to create one...

[Former Member]

Couldn't agree more. That's exactly what I wanted to say! ( maybe I should just delete everything and write down those words haha :grin: )

Also when I said you got to write what you would like to read, I was including, diagrams, images, videos... basically anything that can help you explain what the code is doing. That is not explicitly written in the article, but hopefully people will get it.

Thanks for commenting!

[Former Member]

Michael, I'm very happy you could discuss the topics from my article with your team. This is the kind of thing that motivates me when writing for SCN!

I think most of the people who read your article were nodding their heads, saying "Yes." to themselves as they read through it.  Sadly, I think it's a case where the PMO defines the documentation standards.  Those can be based upon contractual requirements, company policy/methodology, or "That's the way we've always done it."  Unfortunately, it seems as though those who will listen, can't help and those who can help, won't listen.

It's very hard, isn't it? I can perfectly imagine the situation you described: a lot of people who are reading this won't have the "power" to change anything. But discussions like the ones you had with your team can be a start to improve the way projects are handling documentations.

Thanks for this great comment! :smile:

[bjorn-henrik_zink]

My first comment was very well received, thank you. This one might not be as popular!

I am often responsible for approving TS templates and being a part of the PMO.

Let me share a few of my thoughts on how templates are created and followed up.

The templates are usually created by an head architect, a true ABAP geek with numerous years of ABAP experience. The architect creates the document in collaboration with the developers who will peer review it before it is send to the PMO for a formal approval. When new developers join the team they are always asked to review the templates and come up with improvement suggestions as they often have new perspectives that are not already considered. The templates are not static and all team members can suggest improvements continuously. By doing so, the team hopefully will not get the "not invented here" syndrome.

I find templates are necessary for the following two main reasons:

1) Do not reinvent the wheel. I do believe that technical documentation has a lot of common denominators. Having templates helps the developers to not forget the obvious.

2) Speed. I also believe that it takes less time to use templates as developers (both the writers and readers of TD) do not need to figure out the common denominators time and again.

That said, I think a key to successful templates is to be flexible. Flexible in the way that not all parts most be filled out if it does not make sense and that developers are allowed (and encouraged) to enhance the documentation if it beneficial.

[Former Member]

Thanks for the nice blog, Cruz!

I'm still a newbie but I'm totally agree with your thought about TDs.

From a developer's perspective, If I'm new to a project, I would love to have some reading on API documentations instead of the long and dry TDs. I hope that in the future ABAP document generator will be integrated to SAP GUI (like JAVADOC for JAVA)

Currently I find that ABAPDOC2 is very promising: https://cw.sdn.sap.com/cw/groups/abap101-projects-abapdoc2?view=overview

Cheers!

[Former Member]

I have been a developer for 14 years and never once looked at a tech spec to understand what a program is doing.

The issue is that a lot of customer require tech specs to be created. I am currently on a project and the tech specs here are just screen shots of various parts of the development.

We developers understand the lack if need for a tech spec, however, there are other people out there (Customers, Managers, Team Leads, who think they are required and provide a lot of use).

I have been on a project in the past were the template document was over 20 pages long.

Time and time again, I always make comment on the use of a Tech Spec, and am always agreed with. Yet we keep on doing them.

When I write tech specs I use the following format now: -

• LOOP AT T_DATA
  • CHECK MATERIAL IS POPULATED
    • CALL FUNCTION MODULE blah_blah to update material
    • IF error
      • send email
• ENDLOOP

Using the above format could tens of lines of code. It seems to work weel and I have noticed other people doing it now.

I have started to write an ABAP utility that will auto document a program for me. It will read a program and list out the details of bespoke tables, flow logic, Functions used etc. This way, I can estimate a tech spec will take approx 1 day to create. Using my program will do over 50% of it.

Is uses OLE and creates a word docuement that can then be amended furthers, or chopped up and put into the relevant template document.

Thanks

Martin

[Former Member]

Hey Bjorn,

The way you and your team handles templates is very good indeed. However, this is far away from the truth I've seen in many projects: I started hating templates for reasons that are the opposite to everything you just described.

If a team is willing to generate relevant documentation, your suggestions are extremely helpful, but unfortunately they just don't care about the quality, all they want is a "XYZ - Technical Document" file at the project's CMS...

[Former Member]

Read this! I know the guys behind the Codex ABAPDoc projects, and I bet they are also excited with the native abapdoc features on 7.4 :smile:

[Former Member]

Hello Martin, thanks for your comments.

I just replied to Nguyen about the ABAPDoc on the newer ABAP AS version. In the past I also tried to create a "document generator".... However, to be honest with you, I see no value in a TD that has the structure you just described. Why would I ever want to see a incomplete pseudo code in a Word Document after the program is up and running? It's very much easier to go straight down to the code...

On the other hand, a document providing me technical insights would help figuring out that crazy recursive logic that would probably drive me nuts.

Best Regards!

[bruce_hartley]

Hey Mauricio;

Great article - one of the best I've read in quite some time about documentation.

Since my main job is to develop interfaces ( The "I" in RICEF ) in and out of SAP ( and dig for problems when they fail ), there are certain things that I need in my daily job and others that I don't and you hit the nail on the head when you said "see what you have and improve it".

I don't need the documentation to tell me what all the tables are and what all the fields are in the program, what I need documentation for is as follows:

Stuff that is pretty static but vital:

1 - Where is the data coming from?

2 - Where is the data going to?

3 - How does it work at a high level? batch job or manually run?

4 - If a batch job, how often does it run - If manually done, what job description does it?

5 - How do we know an error occurred?

6 - Other important logistics ( holes in the firewall needed for example? )

7 - What are the most frequent errors and what do you do about it ( recovery process )

8 - if part of a chain of programs, what's the previous and next programs in the chain

9 - Important algorithmic parts that are complex or not easily understood

10 - What else outside of ABAP is needed for this to work?

11 - What method is being used to get the data in and out of SAP? - FTP? XI? IDOC's? SOAP? etc

And stuff that is dynamic by nature of the beast but super important:

1 - Who should I contact if it fails ( chain of command )

What also helps is USEFUL comments in the program.  I don't need you to tell me "select from mara".  What I need is "Get material to send to system x" and also make sure your comment is generic about system X because it's probably a different physical system if you are in development, QA, or production.  The first comment doesn't do me ( or anyone else ) any good, the second one tells me in english what the program is doing and WHY.  I don't need you to say MARA, the code tells me that in the SELECT statement that is almost always following right after.  Most if not all SAP programmers know MARA to be the material table and even if they don't they will after reading your comment!  It also helps if you block your comments so that on average you have about 10-40 lines of per comment on average.

Give me the above documentation and code comments and I'm a fan of yours for life.

[#39]

Hi,

great post, and I strongly agree, many TDs are just a waste of space. Personally, my favourite docs contain 3 things: A functional description of how the development is supposed to work,  a reference to the package that the code is located in (and I like to insist on a package per development - embedded in a reasonable package hierarchy). And a diagram of the flow of the code. Why? because the only time anyone looks at a TD after implementation is to debug an issue with the code, and those three things are the only things that I really need to be able to start throwing debug points into the code to figure out what is going on.

I'm currently staring at a whiteboard with a lot of post-it notes on it representing a bunch of code that I'm about to review and update the TD for. So I'm going to be feeling your pain this coming week(s).

Something that might relieve my pain through is some tooling to auto-generate sequence diagrams of code (this actually exists as standard in ABAP, however, AFAIK the ability to export the sequence diagrams into something useful does not. Given the amount of code I have to document, it may be that might code something up - after-all I have done it once already...

Cheers,

Chris

[fred_verheul]

Thx for sharing the cool video Chris, great time management too :smile: !

[Former Member]

Hello Bruce,

Your list would make a good template, one I would not hate :smile: .  Interfaces really have tons of info that must be written somewhere outside the code, as most times the objects are split everywhere between systems, and you got to have something explaining the whole thing.

It's very easy to find tons of bad comments like the ones you just described. Personally, I like to add 2-3 lines of comments right at the beginning of a Form/Method, explaining what that part is doing. It's usually enough to give another developer a brief explanation.

And you don't have even to talk about common tables like MARA, I've seen a lot stupid comments like:

*Read ALV Output Table
READ t_alv_output INTO wa_bla...

Why the hell would someone write a comment like that? Isn't "READ t_alv_output TABLE" enough? :mad:

I worked in a place once where people asked you to add comments like this. If you didn't use them your code was not "well commented". I was a junior programmer at that time, but I can assure you that they are still doing things like that, bragging about how much "quality" their programs have...

Thanks for commenting!

[Former Member]

Hi Chris, thanks for commenting!

I liked the idea of your video. Did you get the chance to keep improving that tool, or your did it just for Innojam?

And good luck with your probably-boring task. Let's hope the TDs you're about to update are the opposite from the ones I mentioned in this article...

See you!

[custodio_deoliveira]

Hi Mauricio,

Great blog again. I have to say I agree with most with you points, but a pair with bjorn-henrik.zink on the need for templates (although I don't really like them).

Also, you might be interested in reading Don’t hold your SAP Custom Development to ransom from matt.harding (in case you haven't yet). I'm working in the mentioned project with Wiki based documentation and it works quite well IMO (and we still have templates for detailed specs).

Cheers,

Custodio

[custodio_deoliveira]

Another interesting blog on this subject is Howto - Write documentation from tom.vandoorslaer

[FabioPagoti]

E nenhum cupcake? 😞

[FabioPagoti]

Sorry to join the conversation like this but the only few things that I REALLY admire in Microsoft is the way they document everything on MSDN.

There are lots of documentation pages where anyone (with a @hotmail - something I do not admire) can comment as would do in a blog post and as a consequence contribute for the documentation.

See an example: http://msdn.microsoft.com/en-us/library/windows/desktop/ms687401(v=vs.85).aspx

[FabioPagoti]

I believe this is part of a team/company culture.

IMHO if the team/company gives enough credit for quality, there is no QA team. Everybody is part of the QA process.

Unfortunately it's quite rare to see more than 1 ABAP developer working on the same SAP repository objects, by the current limitations of the editor and due to the fact the code is centralized. As a consequence, others developers won't complain about a bad TD as they are busy with a different matter.

As scrum emphasize: it's important to have a common definition of "done". Developers are the ones most benefited by good TD (I mean, directly). If writing documentation is not part of the creation of maintenance job, moreover if there is no review within the development process with a different developer, doing/updating a TD it is not required to have something done.

In other words, this is not only about bad ABAP developers: this is about jurassic development processes, elderly culture and finally lack of ownership and accountability.

[FabioPagoti]

Yes we are! https://twitter.com/fabiopagoti/status/337011416768839681

However, there is enough time to use ABAPDOC2 a lot before seeing 7.4 implemented at customers.

[Former Member]

Hey Custodio, thanks for pointing out those articles. Actually I haven't read them, but I'll definitely take a look - wiki based documentation seems a very nice approach.

Thanks for commenting! :smile:

[Former Member]

I agree with you Fabio! I also admire MSDN for the same reasons. Have you heard about Docular? It's an API generator that generate documentation like the AngularJS one: http://grunt-docular.com/ It builds a website from your source code, with categories and a searchbar. It support the Markdown syntax (which github's Readme/wiki syntax are based on). You can use Markdown within code comments or even in separated files. It comes with a disqus plugin to allow visitors to comment on the generated docs. I know it's not for ABAP or Java, ... but it's the best api generator I've seen so far.

Of course generated documentation from source code isn't enough but as I said, Docular handles separated documentation files that can be used to describe for example the overall architecture of your app, or a getting started guide

[alexander_kutz]

I completely agree. The why is always the question. After a few developer or customer person changes you start always asking this question.

That is exactly the reason why I cannot find any good reason for a generated documentation - a generated documentation is only a big printout of the system status. It does not help to understand. The navigation in the system is more efficient than scrolling through a few hundred pages.