Most Python official documentation ranks poorly in search engines, despite being the canonical, advertisement free, community focused resource for Python. Many of the sites that rank higher than the official documentation lead Python developers toward paid resources, sometimes provide incorrect or outdated information, and expose them to risks with aggressive advertisements and tracking. This also devalues the community contributions that go into the (in most cases) excellent documentation, because instead of getting the carefully edited text users will end up with someone else’s take on Python.
Trying queries that I believe should lead to direct documentation, like passing in the full function signature for compile as compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1) doesn’t show the official documentation on Google until the second page, and in many variations the GitHub functions.rst file ranks higher than the rendered documentation. Performance is similar on DuckDuckGo and Bing, in my testing only Kagi returned the official documentation as the top result in this and many other queries.
There are existing issues like this one on docs.python.org SEO, and discussions like this one on Reddit, or this one on HN, or this second on on HN and of course this begs the question, what should be done about it? I imagine that a relatively limited set of CPython core developers and community participants are experts in SEO, and I wonder if there could be some Python organizational resources put toward this since it seems like it could have an outsized impact but also be unlikely to be addressed in depth within the normal pipeline of contributions Python sees. It may also be worth evaluating the alternative representations of the documentation (for example, devdocs.io Python 3.13) that others have used to make the documentation more valuable to developers, perhaps these reorientations of the documentation may naturally provide better search results.
Thank you for bringing this up! Yes I also agree that we need to come up with ways to improve the docs SEO.
We have tried some improvements like adding opengraph metadata to the docs. Definitely would welcome ideas and action items on what we can do about it.
Just as a side note, I think this problem also means it’s very important that the documentation be organized in a clear and coherent way that makes it easy for someone to “drill down” to find the information they need. Although there’s a lot of great info in the docs, it’s not always easy to find the answers to certain questions.
We are always interested in ideas about how to better organize the docs and even more interested to get help doing it. Certainly no one would disagree with “the documentation should be organized in a clear and coherent way.” There are challenges to meeting this goal, including differing audiences with different needs.
I included it just as another link, but the devdocs.io CPython documentation is worth exploring, that project is open source (I have no affiliation with them just liked the presentation they provided). It both has a visual hierarchy which makes navigating and associating documentation easier to use, and a fairly smart search filter that can help when performing keyword searches. Part of the strength is jumping directly to the specific method signatures within broader pages, a pattern that can be challenging with the documentation today.
Another path that I think would be worth exploring is discussing this with developers from Python based projects who have had success in making their content high ranking within search engines. For example. Django seems to have done so, a Google search for “django file class” returns this snippet and top result:
