Documentation Is Evil

There is a tendency in software engineering to believe that documentation is a good thing, and that more is better. I believe that documentation is actually evil; documentation takes effort to write and time to read. However, we need to communicate information and documentation is often the least bad method. That makes documentation a necessary evil, not a good thing. The approach therefore should be to write the least possible to convey the idea, but no more. This site will attempt to keep the writing to a minimum in keeping with this principle.

Of course, Mark Twain often said the same thing, only better (more concisely)...

Anybody can have ideas - the difficulty is to express them without squandering a quire of paper on an idea that ought to be reduced to one glittering paragraph.

He advised the use of plain English (one of my failings is a tendency to be excessively polysyllabic)...

I never write "metropolis" for seven cents when I can write "city" and get paid the same.

And to avoid flowery language (another of my many shortcomings). Note the implicit importance of proof reading to reduce verbosity...

As to the adjective, when in doubt, strike it out.

I hope that I have the time to make the entries in this site short and concise, rather than having to offer Blaise Pascal's apology...

I have made this letter longer than usual, only because I have not had the time to make it shorter

See Also

• All models are wrong