Difference between revisions of "Documentation Is Evil"

From Fellrnr.com, Running tips
Jump to: navigation, search
User:Fellrnr (User talk:Fellrnr | contribs)
User:Fellrnr (User talk:Fellrnr | contribs)
 
Line 12: Line 12:
 
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 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...
 
<center>''I have made this letter longer than usual, only because I have not had the time to make it shorter''</center>
 
<center>''I have made this letter longer than usual, only because I have not had the time to make it shorter''</center>
 +
=See Also=
 +
* [[All models are wrong]]

Latest revision as of 08:49, 2 January 2012

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