Guido van Rossum wrote: > This is an interesting phenomenon. I'm not saying it's good or bad, I'm > just observing it (because it surprised me). Here is someone declaring that > the docs are less accessible than the code. I personally am disappointed, > given the amount of effort that we put in those docs. But maybe this is > true. If we can't get people to peruse the docs, should we bother?
The docs are very well written and of good quality, no doubt, but that doesn't necessarily mean they are accessible. Searching for "python docs" on Google points me to https://docs.python.org/. So far so good, but the landing page doesn't seem very newcomer friendly. It contains a few (technical) topics with links on the left side of the screen while the right side is completely empty; then in the top right corner there is this tiny search bar, which more than easy to overlook. It reminds me of the old PyPI website (https://web.archive.org/web/20170822160042/https://pypi.python.org/pypi) which also had a tiny search bar. The new PyPI design on the other hand is much better: a huge search bar right in the center of the page, impossible to miss. This also suggests to the visitor _"this is a place where you can search for (and, more importantly, find) answers to your questions"_. I think this is what especially newcomers would like to do; being new to something you probably don't feel c omfortable clicking and scrolling through dozens of articles in the hope that you might find what you're looking for. Instead you want a search engine to do the job of crawling and just present you with the best results. So I could imagine, lots of users, even if they land on the docs page, just turn to their search engine instead and then they land on Stackoverflow and the like, but not the Python docs. Hence the docs landing page should probably have a much more enlarged and centered search bar, since searching is a central interaction of users with documentation. Also the various listed categories probably don't sound very newcomer friendly. For example "Library Reference (keep this under your pillow)", how would a newcomer who wants to work with email in Python know that this is the place to look for solutions? These topic headings are good if you're already familiar with Python and/or the docs, but to be attractive for new users they should be more explicit (and explicit is better than implicit). Then other topics like "Extending and Embedding" are not newcomer relevant at all and thus might have a discouraging effect. So a reordering of topics from general to specific, newcomer to expert, and aligned top to bottom could help as well (experienced users will know where to look for their answers anyway). Another aspect is in which way users are pointed to the Python docs from elsewhere (apart from search engines). For example the search bar at https://www.python.org/ seems not to search the docs but other documents like PEPs. Then in the interpreter if people use `help` to search a module for example they're pointed to the online docs (e.g. `help('abc')` mentions https://docs.python.org/3.7/library/abc). Maybe it would a good idea to also provide this online reference for builtin types and functions: so `help(list)` could include a link to https://docs.python.org/3/library/stdtypes.html#lists or https://docs.python.org/3/tutorial/datastructures.html#more-on-lists; especially since if I search for "list" in the Python docs (https://docs.python.org/3/search.html?q=list&check_keywords=yes&area=default) I get all sorts of results but `list` relevant results are at positions 10+ and under different names such as "Data Structures" and "Built-in Types". Similarly `help(sorted)` could point to https://docs.python.org/3/library/functions.html#sorted. This would encourage users to consider the online docs, and once they've appreciated the docs as a helpful resource they're more likely to come back on their own. Then, on a side note, the Python Wiki (https://wiki.python.org/moin/) also spreads some kind of nostalgic atmosphere given how it looks. I could imagine that especially the younger generations feel more attracted by more modern looking websites (for example https://realpython.com/) and also they might (falsely) assume that the content is not completely up-to-date either. So long story short, I think the content of the Python docs is of excellent quality but the way the docs present themselves (are presented) to the outside world, and especially to newcomers, could be improved in order to have a better impact / acceptance. _______________________________________________ Python-ideas mailing list -- python-ideas@python.org To unsubscribe send an email to python-ideas-le...@python.org https://mail.python.org/mailman3/lists/python-ideas.python.org/ Message archived at https://mail.python.org/archives/list/python-ideas@python.org/message/RRH36Z3MDKITU2633FFRVR7KXRLXUIPL/ Code of Conduct: http://python.org/psf/codeofconduct/
