Howto – Write documentation
I know,
The last thing any developer, technical, or even functional profile wants to do, is write documentation. Still, the documentation is a vital deliverable, and some companies even refuse to pay the final invoices if the documentation is sub-par.
This isn’t a blueprint
They’re right you know. Often times, I see documents containing different chapters for all the custom tables, with a list of all the fields. I’ve seen webservice definitions which are basically just an Excel sheet with bright colors and a bunch of technical names scattered around with no explanation whatsoever what the service is supposed to do. Sometimes, I come across design documents with nothing but pseudo code.
This is all useful information that must definitely be in a technical document, blueprint, design or whatever, but it must never be the only information. The developer in the end will need the structure of the table. He/she will need to have an idea about the expected coding and he/she will need to know how to implement the webservice, proxy, handler, whatever. But they also need to know the goal of what they are doing. They need to know the story.
If there is no coherent story behind all this data, than that is exactly what it is. It’s just, pure metadata. Before you can actually consume the data, you need to see how it links together. You need a coherent story, which turns the data into information. Information which you can consume, and apply and over time, turn into wisdom. but let’s not go there just yet. Let’s first see how we can make the data manageable and turn it into information.
Some pointers
1) There’s a very easy tip I would like to share. Don’t write a bunch of technical buzzwords. Instead, tell a story. Tell a story in which you put the end-user as the central actor. My first mentor always told me, “good documentation reads like a good book”. By doing so, you will ensure that the implementation is also done with the end-user as crucial factor in the end. It will result in a process that is oriented towards the user and most of all, make it clear to the developer what his contribution actually is. Better understanding of the expected result, leads to deliverables that are better in line with the expected result.
You may argue that you write the specification for the developer and that you will explain what you mean to him. Never forget however, that in 3 years, someone else will have to make a change to those developments, and that you might not be there to explain your cryptic listing of data.
2) Let someone else read your document, preferably someone who is not involved in that area of work. If he/she comes back and says: “I have no idea what you are trying to explain here” than you must go back and redo it.
3) Don’t only describe the happy route, but also describe how the end-user can get frustrated when he deviates from the happy route and ends up in the “dark wood of error”. Describe how to bring the user back on the happy track before he gets lost.
4) If you’re going to describe the necessary tables, include a data model in MS Access. It makes life so much easier and is so much more understandable than just a listing of tables and describing: “table A links to table B via key fields ID and Hullapalooza”. Seriously: visualize!
5) If you’re going to visualize, don’t step in the rescaling trap. By that, I mean that people insert giant charts in the word document, but rescale it to make it fit and by doing so, it becomes unreadable. Add the image, chart, diagram,… as an attachment, so that the reader can open it in full scale and full quality. Also remember that the reader may not have the right tool to consult the document, so consider making it available as a PDF too.
And while you’re doing that, take some time to sit together with a User Experience consultant, create some screen mockups, and put them in the document as well. (in line and as attachment)
6) Use the word styles for formatting. They help you in making uniform looking documents and they allow for automatic generation of a “Table of Contents” or a “document map”. these are two super-useful techniques to quickly navigate lengthy documents.
7) If your document exceeds 25 pages, consider putting in a management summary.
8) Keep your document and story up-to date! Nothing more frustrating to finally find the documentation on the report you have to change and then discover that the spec is not in line anymore with the implemented reality.
9) Organize your document repository in an intuitive way and remember that in 3 years time, people still have to find your documents. (Consider putting them on the development environment itself to bundle them together with the actual system work) Avoid root folder names like “09_271_X_9”. How about simply giving your root folder the same name as the project which you are working on, maybe preceded with a number for the historic sorting like: “092) Project”?
I know, crazy idea right? Yeah, I’m a real goofbag. 🙂
ROI
These are the pointers I (mostly) follow myself. I’ve had very positive feedback from clients already, because the documentation is actually readable to anyone and it still contains the technical information required by the technical profiles. On top of that, it provides a base for user manuals as it tells the story from the user point of view.
These tips are not only for Development specifications, but they are equally important for blueprints, functional descriptions, user manuals, training material and so many other types of documents you have to write on a project.
It might look as if you’re going to spend more time on the documentation this way, but in reality, you’re actually going to spend less time explaining and reworking the doco and your testing plans and user manuals will get a head start.
Also appeared on my personal blog
Edit: corrected the whitespaces between paragraphs
Using styles in Word documents is good practice as it also makes the documents more accessible to screen readers and allows you to use features such as the document map. It also means that you can quickly create tables of contents and if you save a document as a PDF directly from Word you get embedded bookmarks.
If you want to make all the documentation and presentations you produce more accessible, take a look at the (free) JISC TechDis Accessibility Essentials series.
One thing to watch for with creating PDFs from Word is that if you have an embedded file in a Word document, it doesn't transfer over as a file embedded in the PDF. I heartily recommend circulating PDF copies of documents, but just something to be aware of.
It's a good list (above) and I'm sure further comments will add even more value to this post. But I'll recommend including a few more things just to get the ball rolling:
Hello Tom Van Doorslaer,
I may talk from a different perspective here.
I strongly feel that the way we do documentation depends on how willingly we do that and how clear are we with the stuff and also why are we doing that!
I have seen few documents which serves no real purpose but are there just to follow standards. Moreover with time few documents becomes so long that it is really hard to follow them rather we start looking for alternatives then. The purpose of documentation should be made clear, at least to the developers.
On the other hand, documentation is important if we do not want to forget our experience, of working on different things, which I have realized lately.
To document or not to document is the Q? 🙂
Regards,
Kumud
Kumud.
I think I agree for the most part with what you're saying, but I'd like to offer up some counter points on a few things if I may?
I would suggest that it is not the length of a document that makes it difficult to follow. Instead I think it is more the way in which a document is structured. I'm a little on the fence with regards to length in that I think smaller documents are easier to structure and therefore digest and the longer ones need more consideration which leads to the result you describe.
Certainly if there are different intended audiences for information, there should be different documents. However I think being able to search quickly within a single source is equally valuable. I'm a big fan of having documentation outside of the packaged document format we mostly work with. Wikis and the like I feel offer greater flexibility in this and can offer the best of both worlds with everything in one place yet in "bite size" chunks.
Also whilst I can completely understand not wishing to write unnecessary documentation and I agree whole heartedly that the purpose of any documentation should be clear from the start; I have never found myself in a position where I had too much documentation ... only too little. I can believe that if the documentation was all hard copy and poorly structured such a situation might arise, but I'm not so sure about electronic forms.
Stephen.
Hello Stephen,
Pretty agreeable comment. Hmmm..let's say the document is to document all the changes done in a Project pertaining to ABAP under one document. You can guess how long will that be with time. Certainly easy search pays but If I want to learn something new from that document, not sure but I will be reluctant there. This can be entirely my opinion.
Regards,
Kumud
One thing I would encourage ABAP developers to do is to also add the documentation to the custom object in SAP they have just created / changed. I had to add a new key field to a Z table yesterday and as a last step I went into the table documentation within SAP and just cut and pasted the logic from the requirement "ticket" and changed it a bit for readability, and so now if anyone wonders why that field is there / what it's business purpose is / what problem was trying to be solved, they wil be able to see.
It adds about three minutes to development time, but hardly anyone ever does this.
Most people know the feeling of finding a standard SAP function module that looks useful and getting the ever popular "documentation is not available in English" which means it is not available in any language.
The analysts wher I have been working recently often come and ask me what one of my custom tables / functions / fields is for, and as I have created so many over 12 years I usually cannot remember of the top of my head.
So I press "Goto > Documentation" and suddenly "all is clear" as we love to say in Germany (that's where I work at the moment).
The German business analysts are amazed. They had never encountered a programmer before who had documented their custom objects in SAP, so it seemed a waste of time to them to even try looking for documentation for objects within SAP, even though they knew how.
As you mention documentation needs to be kept up to date, so that is why when I make a change updating the documentation for the changed object is the go.
In my custom code you often see the business requirement in the method / subroutine comments. That follows the maxim - do not document WHAT the code does, as that is obvious, but WHY the code is doing what it does i.e. what problem is it solving.
So in our system if you wonder what a field is for on a custom screen you press F1 and it's use is made clear.
In standard SAP if you see a field called the "reverse scrunge indicator" and press F1 up comes a box saying "reverse scrunge indicator" which is not all that helpful. This drove me nuts so I vowed never to do this myself.
That's enough waffling from me for one day.
Cheersy Cheers
Paul
Hi Paul,
Adding the documentation on the system itself is definitely useful. You're doing a great job there. I already mentioned it in the list as well under point 9, though I kept it more general and not ABAP specific. But it's the same idea.
I feel your pain when you press F1 and you don't get any explanation of what ZZ_GR4_XFY does. So you look who created the field and if you're lucky, he's still around and you can ask him. If he still remembers what it does, or where he put the doco, you're ok. But that's a lot of IFs.
So exposing the doco where it matters is a lifesaver.
Cheers!