Thanks a lot for the review, Eli. Here's a patch which addresses all of your feedback, except for the following:
Perhaps be explicit that there are two types of state, persistent and ephemeral state. That all persistent state modifications and some emphemeral (eg block allocation) are logged, with the remaining ephemeral state (block reports) are handled by the Datanodes communicating two both Namenodes.
Might be worth mentioning that we fence both with the fencers but the NNs also fence operations outside the edits log (eg operations from block reports)
Both of these facts seem more developer-oriented to me, and not particularly pertinent to operators. I think adding this material would only serve to confuse operators, and add little value.
Wrt syncing metadata directories, perhaps worth noting that you only need to sync the edits directory since the shared edits dir only contains edits (people may be confused why the old image they copied there never gets updated)
I already do say that you should copy over the fsimage/edits to the second NameNode, and only put the recent edits in the shared directory. What more do you think should be said?