Wow, Addi, you are a champ. This is one of the most important documents that we could have on our website. Thanks for doing such a nice job of converting that mail list discussion. We need more of that type of effort.
I left this issue open for a while because there sure to be more changes. There is another discussion happening on a related topic. Anyway
I added your patch as-is, except that i converted tabs to two-space. I also folded long lines into about 80-characters wide. The reason for this is very important. I am now going to proceed to make some minor changes and you will see via the commit diffs (see www.mail-archive.com
if you are not subscribed). If each paragraph was one enourmous long line, then it would be difficult to know the changes. (Yes i am adding stuff like that to a new "how to be a developer" document.)
I have left this issue open for a while because there are sure to be more changes. The discussions are not finished.