[TASK] Improve wording and add some additions to migration

[Alagts]

No description provided.

[garvinhicking]

Hi @Alagts !

These are some cool improvements, thank you for taking the time and working on this. It is important to streamline this for both newcomers and existing users of our documentation workflow and get it right.👏👏👏

[brotkrueml]

Regarding the warning examples: I suggest to add a paragraph, like

Problem: anchor not found

or

Problem: manual with given version not found

directly after the heading. I have to read the whole section to get what is wrong. This short introduction eases the understanding of the problem.

[linawolf]

@brotkrueml please let us get this merged. You are welcome to further improve this section in a follow up

[brotkrueml]

@brotkrueml please let us get this merged. You are welcome to further improve this section in a follow up

I am not blocking it. Feel free to approve and merge, I won't approve it for now.

"I am not blocking it."

[linawolf]

Thanks a lot for these great changes