Ever think about documenting design tradeoffs

[Paulo Levi]

When i scan the messages in this list i see many instances of backwards
compatibility design tradeoffs.

Can't change the binary classfile format - adopt a limited transformation,
limit inference, etc etc etc.

And the user visible documentation of the omits these tradeoffs and
irritations.
Wouldn't it be wise to document all of them so that on a eventual "java++",
you wouldn't just copy wholesale library/compiler/runtime design from java
but vanquish these old irritations?

Just a thought i had, don't really know if you're already doing it
internally.