The Principled Documentation Manifesto

I find the "commandments" format to irk me slightly. I realise it lends a ready-made structure to any document, but "thou shalt" is sufficiently fusty that it can rub people the wrong way.

I've found the pattern format to work well in practice, because a well-written pattern pretty much explains itself. In particular, framing the discussion with a problem helps to illuminate when and where a pattern ought to be applied.

In terms of your general thesis in #2-5 that formal specification has failed and that a structured form of informal specification (wrap your head around that one, fellow pedants) ... I'm not sure.

I mean some of what you've argued for seems to me to be a "language design smell" -- just as some of the original Go4 patterns were seen in retrospect to be. So for example when you argue for taking a contractual approach. Why shouldn't that be in the language? It's not as though you have to go all the way to writing Z specs or Coq proofs. Personally I'd be perfectly happy to step up to Eiffel contracts.

Guarantees embedded in source code also have the nice property that they are slighly less likely to turn out to be filthy horrid lies; just as is generally thought of sourcecode comments.

I agreed with point 7, about stating the end state of the method rather than its process. I feel the same way about tests; I find test doubles to be thoroughly unsettling because I wind up explaining the logic of my program twice, instead of separating mechanism and validation. Perhaps such "naked mechanism" is just another indicator of code that will require high coupling.

Where you went wrong was that you, like I, assume that things with "database" on the label have silly-old fashioned notions like a fanatical focus on data safety.

I also agreed strongly with 8 and 9. Sometimes I look at the front page of HN and it is totally unintelligible gibberish. Having to know the intricate injokey history of two dozen sequential puns to run a piece of software drives me up the flaming wall. It's one of the things I least like about the ruby ecosystem.

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/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.

A bit of time making this more concise and cleaning up the language would go a long way when you get the time. Clarity above all other virtues for documentation, goes doubly for meta-documentation.

The link at the bottom ("I believe HyperDex documentation to incorporate these principles") is wrong: it should be /doc/, not /docs/.