Your claim that "Chances are, if you're reading this, you already are a disciple" turned out to be true for me. Good job. I think everyone knows good and bad

Your claim that "Chances are, if you're reading this, you already are a disciple" turned out to be true for me. Good job. I think everyone knows good and bad documentation when they see it, but breaking it down into actionable rules like this is great. If I could add something, it would be that there are both local and global assumptions, and both need to be specified. There are rules like "this input array must be sorted" and there are rules like these: http://blogs.msdn.com/b/oldnewthing/archive/2006/03/20/555511.aspx http://blogs.msdn.com/b/oldnewthing/archive/2006/03/20/55551... (yes, it's bad that this is a blog post and not documented officially anywhere AFAIK). For example, sometimes it's surprisingly hard to find out that the developers of some library you're using assumed that callbacks never throw exceptions, even though it seems to work almost every time.