When I started writing the documentation for a software product I make I went with Markdown. It was what I knew and I thought it was great.
As I started writing the documentation though, Markdown's drawbacks became more apparent. Especially as the software I'm making is multi-platform and there are features that exist in one platform and not the other and I'd like to include/exclude documentation of those features based on platform, and the fact that I'd like the documentation for each platform to contain images from the program running on that platform, and so on, and this is not something that Markdown handles well.
And so I switched to ReStructuredText. RST is not as clean or as simple to write compared to Markdown, however if you are producing documentation then it is much more flexible. I can live with less clean syntax in order to get the flexibility to do what I need to do.
As I started writing the documentation though, Markdown's drawbacks became more apparent. Especially as the software I'm making is multi-platform and there are features that exist in one platform and not the other and I'd like to include/exclude documentation of those features based on platform, and the fact that I'd like the documentation for each platform to contain images from the program running on that platform, and so on, and this is not something that Markdown handles well.
And so I switched to ReStructuredText. RST is not as clean or as simple to write compared to Markdown, however if you are producing documentation then it is much more flexible. I can live with less clean syntax in order to get the flexibility to do what I need to do.