I wonder how would this work in an international dev teams. While code is always the common language (including the UML), markdown requires you to have really good english writing skills. This can get messy really fast.