It looks like the parallel hierarchies of builders and writers [^1] aimed to provide high flexibility in the early days of JavaDoc, when the architecture had to prepare for every possible future. However, the now-future has shown that much of that flexibility has never been used.

One problem with that unused flexibility is that it makes the architecture more complex than it needs to be. The price for maintaining the architecture is too high for what it provides. We should reconsider a tradeoff between flexibility and maintainability with what we now know.

A few initial observations. Builder and Writers look like an implementation of the Bridge design pattern from GoF. If so, then not only is it overkill, but also broken: some writing logic has leaked into builders and some building logic has leaked into writers.

It looks like the "Builder" and "Abstract Factory" design patterns could achieve the same effect but much more cleanly. Or, since we don't need a product (as defined in the "Builder" design pattern) as a documentation page is written to a file opaquely, maybe some variant of the "Template Method" would do even better. TBD.

[^1]: https://openjdk.java.net/groups/compiler/javadoc-architecture.html