Sourcegraph: "A single example is worth 1000 lines of documentation"

I initially disagreed, but the actual quote is better: &quot;<i>The right example</i> is worth a thousand lines of documentation.&quot;<p>There are many cases where explaining things is better, and a well-crafted explanation with a few sparing examples is often the best way to communicate an idea — but there are some cases where a particular example is clearer than any explanation could hope to be.

&quot;But they didn&#x27;t go through and parse the code like we do. It couldn&#x27;t tell you who else uses this particular function or repository.&quot;<p>It may have, but perhaps didn&#x27;t present the UI for external users. Our internal version of Codesearch based on Grok (<a href="http://www.stanford.edu/class/ee380/Abstracts/121010.html" rel="nofollow">http:&#x2F;&#x2F;www.stanford.edu&#x2F;class&#x2F;ee380&#x2F;Abstracts&#x2F;121010.html</a>) is far more powerful and works just like an advanced IDE -&gt; find usages, callers, implementors, overrides, all kinds of auditing&#x2F;analysis layers too.<p>Some Googlers practically live in Codesearch rather than use the local IDE indexing :)

Really cool looking site, but I&#x27;m not entirely sure how to use it! I went to the site used one of the suggested searches (djano Charfield). A lot of the search results actually brought me to a 404 page (confusing?). Even then, since most of the examples listed were classes, I&#x27;m not entirely sure how this relates to &quot;a single example...&quot;, as these weren&#x27;t examples?<p>At the end of the day I love Javadocs though - I really feel like I get the best understanding from them because of ability to easily browse packages, go up and down inheritance hierarchy, see all implementing classes, and there are typically some good examples in it too.

For me this really depends on the examples. I tried learning Haskell years ago and the examples I found were confounding. Reading through documentation and books on the language was much more helpful. Unfortunately, I still suck at Haskell.

I find most the examples I need in Stackoverflow, along with community ratings and comments.<p>Which reminds me of another idea which I think I remember Jeff Attwood talking about: We all copy these snippets from websites into our code. Those snippets might have bugs that are later fixed by others on the web, or the APIs change or get deprecated, etc. It would be good to have a reference from the code to the web page so in the future you can remember where that snippet came from and look it up and maybe see if the community&#x27;s recommendations have changed. But even better would be if the bugs that were fixed by the web-community ended up back in your code automatically. So imagine Stackoverflow with a gist-type comment system for the code snippets with versioning and community editing, and then you could somehow do a pull on those gists and grab the community&#x27;s wisdom automatically.

My only question is: why do they spawn git&#x2F;hg processes? Why not use <a href="http://libgit2.github.com/" rel="nofollow">http:&#x2F;&#x2F;libgit2.github.com&#x2F;</a> (git) and some other library for Mercurial instead? That way you&#x27;re not spawning and killing off processes, you just send data from a library

Examples and documentation are not substitutes in my mind. If you want your work to be used, you need both.

For RoR&#x27;s method_missing give me the docs<p>For apache configuration, give me the examples!<p>I really like the use case of helping upstream maintainers decide on method deprecation&#x2F;adding helper functions. Fantastic idea

Examples usually show you how do things like a parrot, but you don&#x27;t get the idea of why these things happen as they do without some documentation.

I write ruby code. I have used snippets that I didn&#x27;t fully understand. It turn out in the usual way &quot;it works but I don&#x27;t understand exactly how...&quot;. I ended with <i>simpler</i> code that I understand, was able to write test and all by reading the documentation.<p>Depends on the example, as other users said.

I&#x27;m extremely interested to see how Sourcegraph continues to define &quot;right example&quot; down the road. Collaborative filtering and more powerful heuristics both spring to mind as possible options.

Just put a good example WITH the doc. Thats.. how its done :)