We all have to look documentation up at some point. While the 'help' built-in is really nice, it does not always present the documentation I want since docstrings tend to be overly short and technical. Sometimes I want a more detailed explanation of how to use something. That's when I pull up docs.python.org (actually, I usually use docs.python.org/dev/ since I almost always use Python right out of svn).
But one must find the documentation they are looking for. For the stdlib the module index or the overall index tends to be enough. For the C API the index is the only way I can find anything. But that still requires clicking through some web pages which is not always the fastest way to do thing. Plus I also end up hoping I can figure out the name of what I want.
That's where search engines like Google come in. We have the search bar which goes through Google to find stuff, which is handy. But is there any way we can make it even more handy?
One way is through the built-in search bar in Firefox. I wrote a search engine plugin that adds searching the Python docs through Google. The plugin does use the Sherlock format, though, so it is rather Mozilla-centric.
It might be nice to rewrite it to use the OpenSearch standard. Writing an OpenSearch description document for the Python docs that also goes through Google should not be too bad. That would allow IE 7 users to also have a search engine plugin for the docs. I personally won't write the plugin until I switch from Camino to Firefox for performance (probably not until Firefox 3 comes out which is going to move over to Cocoa widgets and Cairo rendering).
Another thing would be to use Google Co-op. With that we could have search terms that matched the full dotted name of an object to return the call signature and the first two lines of the object along with a link directly to the object's full documentation.
But for that to work I think we need better indexing of the documentation. And for that I think we need good semantic markup and a better way to have the community help with documentation, but that I will save for another post.
