Personal Insights
recommendations for creating documentation
Dear community, a colleague who is studying while she is also working for my company has recently created a documentation for users. In my role as a coach for trainees and students, I supported her on this topic.
After she was done with the documentation, I asked her if she could compile her experiences as general recommendations on the topic of “creating documentation”. And then share them with her colleagues who are also in training or studying. Because the task of writing documentation occurs in everyday developer life. Sometimes it’s documentation for users, sometimes it’s a requirement, sometimes it’s an error that has to be documented.
She was happy to do that and I think, all in all she did that very well. That’s why I talked with her boss so that we were allowed to publish these recommendations – perhaps trainees in other companies will benefit, too?
The recommendations are now available on GitHub as markdown documents in English and German. Anyone who’s interested can make improvements and extensions.
Best regards and please stay healthy
Michael
P.S.: Interested in a hand-picked round-up of the best ABAP development links every week? Check ABAP Weekly.
P.S.S.: Tired of reading blogs? Check SAP Online Track on YouTube.
Very Nice! This guideline is well thought out. My struggle and usually my second draft is to remove all slang. When I read my document out load - it sounds fine to me with the slang included. So I really have to be careful.
Another small tip - read your document out loud.
Hey Michelle, thanks for this great advice. I've added it to the collection 🙂
Interesting concept. "Sufficient documentation" remains highly elusive at my company. Everyone has a different definition of such. I will check this out.
Same situation I've seen in many companies. I think we need something like "clean documentation" 🙂
Hi Michael,
What is written in B is applicable to many things, even e-mails, inside a company.
A is special! Documentation needs to have a value, a pourpose…who I’m writting this to? Why? Very nice.
I created the GitHub repository a little bit more generic and not tied to the topic described in this blog only. In my opinion, there are more recommendations for other topics possible, as you wrote.