Thursday, December 13, 2007

Documentation Is For Computers To Read

RSpec plus Cruise Control equals a self-verifying, interactive documentation system.

Every time my codebase changes, my documentation pings me on Campfire.

I can run my documentation as code and literally prove or disprove every word of it.

I can't remember the last time I put a comment in my code.

I don't think human-readable documentation should be allowed.

If I wanted a flame war I'd call this "Documentation Considered Harmful." But it's not really harmful. It's just irresponsible. Writing documentation in English is like handling source control by manually copying and renaming files.