<story><title>An API is only as good as its documentation</title><url>https://rocketeer.be/blog/2015/03/api-quality/</url></story><parent_chain></parent_chain><comment><author>cbd1984</author><text>Good documentation includes examples.&lt;p&gt;Good documentation does not &lt;i&gt;rely&lt;/i&gt; on examples.&lt;p&gt;An example can provide a base to start from, a beginning point from which further hacking can ensue.&lt;p&gt;However, an example, like a picture, can&amp;#x27;t say &amp;quot;ain&amp;#x27;t&amp;quot;: Examples can only show you what you &lt;i&gt;can&lt;/i&gt; do, never what you &lt;i&gt;cannot&lt;/i&gt; do, or what you &lt;i&gt;should not&lt;/i&gt; do.&lt;p&gt;Further, examples are inductive, and it takes a massive amount of induction to get &lt;i&gt;all&lt;/i&gt; of the rules of a system. However, once someone&amp;#x27;s done something, they&amp;#x27;ve internalized it a lot better than if they&amp;#x27;ve only read about it.&lt;p&gt;Examples should, therefore, allow people to see the &lt;i&gt;intended use&lt;/i&gt; of an API. How do the developers &lt;i&gt;want&lt;/i&gt; people to use their API to solve problems?&lt;p&gt;Documentation is permissive: &amp;quot;You can use this tool to do this.&amp;quot;&lt;p&gt;Examples are normative: &amp;quot;You should use this tool this way.&amp;quot;&lt;p&gt;&lt;i&gt;Both&lt;/i&gt; are needed. I focus on examples because good examples are not as common as they should be.</text></comment>
<story><title>An API is only as good as its documentation</title><url>https://rocketeer.be/blog/2015/03/api-quality/</url></story><parent_chain></parent_chain><comment><author>pavlov</author><text>I have a corollary of sorts:&lt;p&gt;&lt;i&gt;A framework is only as good as its UI.&lt;/i&gt;&lt;p&gt;This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine&amp;#x27;s editor). But Smalltalk and NextStep&amp;#x2F;Cocoa had a grasp of this too.&lt;p&gt;Even without a GUI, the interface matters. Rails&amp;#x27; &amp;quot;generate&amp;quot; and &amp;quot;console&amp;quot; commands are a major part of its appeal.</text></comment>