[riwsky]

You would be wrong. The closer documentation is to the code, the more likely it is to be seen, and to be updated. Reading and writing the docs are more common operations than “writing a new doc transformation tool” by at least 4 or 5 orders of magnitude; the ease of writing new doc transformation tools should not be the determining factor in a design.