Thanks for the thorough critique! Obviously doing all of this is a ton of work, so it's not going to get done right away, but none of this is inconsistent with our existing long-term plans for Twisted's documentation. I hope that if you do get forced to work with Twisted again we will have made the learning experience considerably smoother :-).