On Fri, Jan 28, 2011 at 1:32 PM, Raymond Hettinger <pyt...@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 -- http://mail.python.org/mailman/listinfo/python-list