Skip to Content
Personal Insights
Author's profile photo Michael Keller

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.

Assigned tags

      6 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Michelle Crapo
      Michelle Crapo

      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.

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      Hey Michelle, thanks for this great advice. I've added it to the collection 🙂

      Author's profile photo Peter Monaghan
      Peter Monaghan

      Interesting concept. "Sufficient documentation" remains highly elusive at my company. Everyone has a different definition of such. I will check this out.

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      Same situation I've seen in many companies. I think we need something like "clean documentation" 🙂

      Author's profile photo Felipe Silva
      Felipe Silva

      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.

      Author's profile photo Michael Keller
      Michael Keller
      Blog Post Author

      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.