Move from asciidoc to Markdown

[bezirg]

We use some asciidoc in the repo, let's get rid of it

[Unisay]

I don't know why it was decided before me that ASCIIDoc is a thing to use, I assume there were reasons. (I'd prefer to learn about them from an ADR, but I couldn't find one, probably there isn't, unfortunately)

Its also fair to assume that one alternative is not universally better than another (otherwise we wouldn't have this choice?), so there must be aspects that are better in ASCIIDoc than in Markdown.

The task description is very quick, it doesn't let me answer the main question "Why?".

• Why would this repository switch from MD to AD?
  • What problem is being solved?
  • What new problem is being created?
• What are the consequences of such switch?
• Is there going to be a decision record explaining all the relevant context,so that in 1 year we don't get another issue "Switch from MD to AD."

[bezirg]

@Unisay Checking now our discussion, the reason is that AsciiDoc does not render properly in Github. Specifically the links were/are broken.