rewritte old proposal api documentation to markdown

The Description subsection of AskUser is missing. It is hard to review a PR that mixes markup changes with editorial changes like this :-(