For certain use cases, markdown is arguably the best solution. For a team that uses an SCM like github (or any of the ones that natively render markdown), and that also has simple documentation needs, I can’t imagine a better solution. Markdown is fast to create, can be read rendered or not, can be included in your project repo and in pull requests. Images are easy in markdown, simple tables are easy in markdown (complicated tables very quickly move into don’t bother territory though). It uses the tools and workflow you already have to solve a problem very well.
If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.
If you need something more complicated than markdown can provide (depending on your renderer, that could something as trivial as line breaks inside the cells of a table), then it’s obviously not going work. But for any solution that’s great in one use case, there’ll be others where it’s completely impractical.