Regarding multisig, I agree that it's advanced and that many developers won't use it.

Regarding P2SH, I strongly disagree. Even if developers don't want to generate their own P2SH addresses, they need to know how to spend to other people's P2SH addresses.

Now, here's where I messed up: I left the details above unstated. I knew P2SH address support was essential in any app which pays people, but I never explicitly mentioned that fact. Once we figure out where everything is going, I'll add a paragraph telling developers what they need to know.

So here's my recommendation, although I'm happy to talk about it more: move P2SH back into Transactions. Multisig will have to go back to Transactions along with P2SH since that's all P2SH does right now. However, the contract-like example in the P2SH/multisig section will need to be changed, and the reference to that example in the Escrow subsection will also need to be changed.

If you agree, I suggest you move the text around and then either (1) make the changes to the examples and images yourself or (2) open an issue and assign it to me to make the changes, which I can do in the next few days.