The only two things markdown is absolutely terrible at right now is maths (because it's not LaTeX) and writing things like vertical Japanese with furigana (cert

The only two things markdown is absolutely terrible at right now is maths (because it's not LaTeX) and writing things like vertical Japanese with furigana (certainly, throwing HTML at that problem works for both cases, but it makes things also incredibly untidy for your documentarians). For everything else, there is basically no reason not to use it if you want to write documentation for people to read, rather than produce a typeset product for people to consume.