Use the Source Luke

[Jack Diederich]

On Fri, Jan 28, 2011 at 1:32 PM, Raymond Hettinger <python at rcn.com> wrote:
> I hoping a new trend will start with dev's putting direct
> source code links in their documentation:
>
>  http://rhettinger.wordpress.com/2011/01/28/open-your-source-more/
>
> I'm looking for more examples of projects that routinely
> link their docs back into relavant sections of code.
> Have any of you all seen other examples besides
> the Go language docs and the Python docs?

I think you overestimate how common it used to be to carry around the
sourcecode for the software you use compared to now;  In the past it
wasn't even always possible - if the Sun cc compiler core dumps you
have no recourse to code.  Promoting the idea of doing it is good
because it /is/ a novel idea to many people.  Promoting the idea of
making it extremely easy via documentation links is good because it is
new as well.

Modern tools are making this easier than it used to be so your call
for making it easier still is well timed.  Github/bitbucket/launchpad
have combined the source with documentation; github especially because
the README on github is the canonical documentation and the source is
only one mouse click away.  ack-grep has changed my life.  Sure, I
could always do the same thing in the past with find+grep but ack-grep
makes it so easy (switches for language file types!) that I use it
much more;  I have "ag" aliased to "ack-grep --python" and I use it
all the f'ing time because it costs me near zero to do so.  Likewise I
have an alias "cdp" that "cd"s me into the directory where any given
python module lives.  "cdp collections" puts me straight into
"/usr/local/lib/python2.6" - again, it makes it so easy to look at
sourcecode that I do it all the time.  It is usually quicker to do
cdp/python/import module_name/help(module_name) than to look up the
docs.  Worst case the docstrings suck and I just read the code.

* Anecdote.  I was in a room with Tim Peters and has some questions
about the interface to code he wrote so I thought "Hey, I'll just ask
Tim!"  I asked him and he replied "I'm not sure what you're asking -
do you want me to read the code aloud to you?"  So I just went and
read it.

-Jack