APT was adopted, as recall, as it was what maven gave you. It wasn't that anyone chose it deliberately: it was what there was.
Forrest, which renders very well into multiple formats, is superior to markdown & APT for outputting to, say, PDF, but it's been an under-staffed OSS project for a long time now, and while we use it for some of our site, that's it.
What does MD bring to the table?
- IDE support
- editors like Mou —this can render the content alongside the markdown
- tools to export MD from google docs &c
- Automatic rendering on github simply by pushing the artifacts. This is great when developing your own branch on github: push and you can share the text, yet it also works for ASF content that is mirrored
Best of all: anyone who knows markdown can edit the documents. We'll be (hopefully) opening up editing to more people, hence (again, hopefully) improving the quality of the docs.
Regarding all-or-nothing, you don't have to migrate 100% of the site in one go. Sub-project-by-sub-project will work well.
One thing before applying it though: get pending doc patches in first.