The really good insight author Brian Button brings to this article is that the best sample code for other people to look at as they try to use your program code, is the test programs you should be writing anyway. Good unit tests explore the limits of the software they are testing, and they must be kept up to date with code changes, while ad-hoc sample code in separate documentation tends to get out of date as the code is revised (and documentation is not). Nobody likes writing and maintaining documentation, but if the test code is simple and readable, separately maintained documentation is unnecessary.
His only problem is that very large programs have so many test programs that finding the piece of code you need to look at can become difficult. Button suggests maintaining a roadmap of test programs -- while admitting that this roadmap document suffers the same flaw as all separately maintained documentation. He hopes the tool vendors will eventually get around to solving that problem.
Me, I'm a tool-maker. There is an easy solution to the problem. Easy, that is, for a compiler-writer like myself: Just invent special syntax in the test programming language that designates where this item fits on the roadmap and what the summary line there should be. The compiler can insist on this syntax, so your (test) program won't compile without it, and then it can automatically build the roadmap from all the test programs. The compiler can't force you to put meaningful comments there, but at least the foolish or out-of-date remarks will be there staring you in the face when you add revisions to the test code.
There is more in the article that I won't (and probably shouldn't) repeat here, but the fundamental idea is simple: Keep the test code simple, name the test programs descriptively, and release it to the users to look at. I'm working on a couple projects destined for open-source release, and I plan to use this idea extensively.
Thank you Brian.