Thanks for the write-up. Some comments.
1. It would be useful to highlight the motivation of the controlled shutdown tool. Basically, it reduces the unavailable window. If we simply shutdown a broker without running the tool first, partitions with leader on the broker are not available until the new leaders are elected. Since we currently elect leaders sequentially one partition at a time and each leader election involves reads/writes to ZK, it may take some time for all leaders to be elected, especially when there are many partitions. Running the controlled shutdown tool allows us to move the leader proactively one at a time and thus reduce the unavailable window.
2. We also need to add that once the controlled shutdown tool runs successfully, one can shutdown the broker as normal.
3. We need to describe how to find the controller.
4. It would be useful to describe the list-topic and the create-topic tool as well.