Stop writing Technical Documentation nobody will ever read
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! 🙂
In my experience it is essential to understand the scope and purpose of a TS/TD/TSD. I have worked on projects where as per client mandated guidelines we had to literally paste code from ABAP Editor. This was pushed from client side under the reason of "well maintained documentation". Several clients insisted on code comments and worst of all, commenting each and every data declaration, processing block, and executable statements. It was tough to meet such expectations.
On the other hand, there were couple of clients, who had a single document for FS and TS. It had clear sections for functional part and technical specification.
Technical part contained overview of logic, technical components details etc.
Thus if a user reviews the document he gets the entire life cycle of that object, from business requirement to delivery. This was a really best way to maintain documentation as it had the core or essence of the development captured in it.
Hiya, I think it is point worth noting that some areas of the world have cultural differences that mean they are more or less accepting of making the jump to alternate ways of documenting code.
I'm not saying that cultural differences should stand in the way of adopting and trying out better practices, but be aware for some people such ideas are much harder to stomach than for others.
-- having a fluffy hr type morning, cheers, Chris
with ABAP 7.4 we have ABAP Doc integrated into the development environment.
See the introduction blog ABAP Doc from Michael Schneider
Hope writing technical documentation makes more fun for you now.
Developers can use the same tool for docs as for code.
What I like most is the possibility to see the documentation of a development object on every usage in the code editor.
Next step on our roadmap is a document generator for offline docs in HTML.
What do you think?