<?xml version="1.0" encoding="UTF-8"?><rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
		>
<channel>
	<title>Comments on: The Uselessness of Documentation</title>
	<atom:link href="http://www.zanfar.com/2009/the-uselessness-of-documentation/feed/" rel="self" type="application/rss+xml" />
	<link>http://www.zanfar.com/2009/the-uselessness-of-documentation/</link>
	<description>The Ramblings of an OCD Engineer</description>
	<lastBuildDate>Fri, 16 Jul 2010 06:07:18 +0000</lastBuildDate>
	<sy:updatePeriod>hourly</sy:updatePeriod>
	<sy:updateFrequency>1</sy:updateFrequency>
	<generator>http://wordpress.org/?v=3.0</generator>
	<item>
		<title>By: zanfar</title>
		<link>http://www.zanfar.com/2009/the-uselessness-of-documentation/comment-page-1/#comment-4</link>
		<dc:creator>zanfar</dc:creator>
		<pubDate>Thu, 04 Jun 2009 02:31:06 +0000</pubDate>
		<guid isPermaLink="false">http://www.zanfar.com/?p=6#comment-4</guid>
		<description>I&#039;m pretty sure the tag &#039;rant&#039; and the two qualifications in the post mean that I don&#039;t think documentation &quot;should be discounted entirely.&quot; Second, code documentation (within reason) falls almost completely under the category of &quot;component documentation&quot; a facet I specifically allowed was necessary.

That out of the way: abstraction is most certainly NOT the key to elegance.

Sometimes, abstraction is a part of an elegant solution. Abstraction, by its &lt;a href=&quot;http://www.answers.com/topic/abstract&quot; rel=&quot;nofollow&quot;&gt;very&lt;/a&gt; &lt;a href=&quot;http://en.wikipedia.org/wiki/Abstraction_(computer_science)&quot; rel=&quot;nofollow&quot;&gt;definition&lt;/a&gt; requires that you ignore something. In a very few cases this is perfectly safe, however, in most cases each of these things that you ignore will impact your final product in some measurable way.

My favorite example is file systems. Linux likes to say that &quot;everything is a file&quot; and Windows says &quot;everything is local.&quot; Although both these philosophies can allow a wonderful set of features to the product: *nix&#039;s hardware-independent file tree, and Windows&#039; ability for a dumb app to use complex distributed data stores, they also introduce &#039;glitches.&#039; As a developer, you must completely understand the effects of these abstractions, only then are you able to even attempt to work around them, and build a &lt;a href=&quot;http://www.joelonsoftware.com/articles/LeakyAbstractions.html&quot; rel=&quot;nofollow&quot;&gt;leak-proof abstraction&lt;/a&gt;.

I&#039;ve found that most of the frustrations people have with technology are effects of abstractions. I love my iPod, it keeps me sane, and as much as I believe that Steve Jobs is quite possibly Beelzebub&#039;s son, it has a wonderful design, and decent interface. However, that interface is abstracted. It&#039;s really one big button that someone decided should do about 30 different things, depending on its state. Herein lies my frustration. I am unable to wake my iPod out of its sleep/screen saver mode without changing something else. Some developer at Apple, while abstracting away it&#039;s interface, forgot to treat the sleep state as a programmatically discrete state. Instead, sleep is either the play or pause state, meaning that the buttons do what they would do in those two states. What they should do, is wake the device up. So to see the currently playing track, if my iPod is asleep, I have to change the volume, pause, skip tracks, or move to the ratings screen.

Some things are hard and ugly because there is no way to do them otherwise, and that makes us want to abstract them so they&#039;re pretty. Most of the time this works, but when you abstract, you have to make sure you put limits on the abstraction&#039;s use, or you&#039;re going to hit a leak, and that&#039;s when you&#039;re &quot;infinite space, infinite time&quot; model causes a virtual memory error.</description>
		<content:encoded><![CDATA[<p>I&#8217;m pretty sure the tag &#8216;rant&#8217; and the two qualifications in the post mean that I don&#8217;t think documentation &#8220;should be discounted entirely.&#8221; Second, code documentation (within reason) falls almost completely under the category of &#8220;component documentation&#8221; a facet I specifically allowed was necessary.</p>
<p>That out of the way: abstraction is most certainly NOT the key to elegance.</p>
<p>Sometimes, abstraction is a part of an elegant solution. Abstraction, by its <a href="http://www.answers.com/topic/abstract" rel="nofollow">very</a> <a href="http://en.wikipedia.org/wiki/Abstraction_(computer_science)" rel="nofollow">definition</a> requires that you ignore something. In a very few cases this is perfectly safe, however, in most cases each of these things that you ignore will impact your final product in some measurable way.</p>
<p>My favorite example is file systems. Linux likes to say that &#8220;everything is a file&#8221; and Windows says &#8220;everything is local.&#8221; Although both these philosophies can allow a wonderful set of features to the product: *nix&#8217;s hardware-independent file tree, and Windows&#8217; ability for a dumb app to use complex distributed data stores, they also introduce &#8216;glitches.&#8217; As a developer, you must completely understand the effects of these abstractions, only then are you able to even attempt to work around them, and build a <a href="http://www.joelonsoftware.com/articles/LeakyAbstractions.html" rel="nofollow">leak-proof abstraction</a>.</p>
<p>I&#8217;ve found that most of the frustrations people have with technology are effects of abstractions. I love my iPod, it keeps me sane, and as much as I believe that Steve Jobs is quite possibly Beelzebub&#8217;s son, it has a wonderful design, and decent interface. However, that interface is abstracted. It&#8217;s really one big button that someone decided should do about 30 different things, depending on its state. Herein lies my frustration. I am unable to wake my iPod out of its sleep/screen saver mode without changing something else. Some developer at Apple, while abstracting away it&#8217;s interface, forgot to treat the sleep state as a programmatically discrete state. Instead, sleep is either the play or pause state, meaning that the buttons do what they would do in those two states. What they should do, is wake the device up. So to see the currently playing track, if my iPod is asleep, I have to change the volume, pause, skip tracks, or move to the ratings screen.</p>
<p>Some things are hard and ugly because there is no way to do them otherwise, and that makes us want to abstract them so they&#8217;re pretty. Most of the time this works, but when you abstract, you have to make sure you put limits on the abstraction&#8217;s use, or you&#8217;re going to hit a leak, and that&#8217;s when you&#8217;re &#8220;infinite space, infinite time&#8221; model causes a virtual memory error.</p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Leah Shanker</title>
		<link>http://www.zanfar.com/2009/the-uselessness-of-documentation/comment-page-1/#comment-3</link>
		<dc:creator>Leah Shanker</dc:creator>
		<pubDate>Wed, 03 Jun 2009 22:05:03 +0000</pubDate>
		<guid isPermaLink="false">http://www.zanfar.com/?p=6#comment-3</guid>
		<description>BTW, Welcome to the blogosphere!

You know, you needn&#039;t bother with any other category besides &quot;Rants&quot; :D</description>
		<content:encoded><![CDATA[<p>BTW, Welcome to the blogosphere!</p>
<p>You know, you needn&#8217;t bother with any other category besides &#8220;Rants&#8221; <img src='http://www.zanfar.com/wp-includes/images/smilies/icon_biggrin.gif' alt=':D' class='wp-smiley' /> </p>
]]></content:encoded>
	</item>
	<item>
		<title>By: Leah Shanker</title>
		<link>http://www.zanfar.com/2009/the-uselessness-of-documentation/comment-page-1/#comment-2</link>
		<dc:creator>Leah Shanker</dc:creator>
		<pubDate>Wed, 03 Jun 2009 22:01:31 +0000</pubDate>
		<guid isPermaLink="false">http://www.zanfar.com/?p=6#comment-2</guid>
		<description>I&#039;m a big fan of the 80/20 Rule, but in this case I don&#039;t think that just because 90% of documentation is useless to you means that documentation should be discounted entirely.

I think you applied-type Engineers really are too focused on suffering through a more difficult method of solving your problem simply because hard work builds character. Sure, I&#039;m an intelligent problem solver: I can read through someone&#039;s spaghetti code (most likely not CS educated) and determine exactly what each statement is doing... but why would I want to suffer when it&#039;s unnecessary? Abstraction, my friend, is the key to elegance.

Documentation is laughably simple to write nowadays, especially for source code. You can generate your documentation (even with an extraordinarily complex Object-Oriented taxonomy) straight from the comments and even in some cases your function/variable names/types.

You remind me of &lt;a href=&quot;http://www.boingboing.net/2009/01/12/man-takes-26-years-t.html&quot; rel=&quot;nofollow&quot;&gt;this guy&lt;/a&gt;.</description>
		<content:encoded><![CDATA[<p>I&#8217;m a big fan of the 80/20 Rule, but in this case I don&#8217;t think that just because 90% of documentation is useless to you means that documentation should be discounted entirely.</p>
<p>I think you applied-type Engineers really are too focused on suffering through a more difficult method of solving your problem simply because hard work builds character. Sure, I&#8217;m an intelligent problem solver: I can read through someone&#8217;s spaghetti code (most likely not CS educated) and determine exactly what each statement is doing&#8230; but why would I want to suffer when it&#8217;s unnecessary? Abstraction, my friend, is the key to elegance.</p>
<p>Documentation is laughably simple to write nowadays, especially for source code. You can generate your documentation (even with an extraordinarily complex Object-Oriented taxonomy) straight from the comments and even in some cases your function/variable names/types.</p>
<p>You remind me of <a href="http://www.boingboing.net/2009/01/12/man-takes-26-years-t.html" rel="nofollow">this guy</a>.</p>
]]></content:encoded>
	</item>
</channel>
</rss>
