rewritte old proposal api documentation to markdown
fix headers
better wording (thanks to ancor)
add missing section and some typo fixes (thanks to mvidner)
fix hashtag position
Merge pull request #245 from yast/improve_doc

rewritte old proposal api documentation to markdown