Improving the Python tutorial for beginners


For some time, as a software developer with a daily practice of Python, I’ve been introducing some people around me to Python.
I tried several times to hand them the Python tutorial as an introduction and every time I got the same feedback of them being overwhelmed. Taking some step back, I realize that I was introduced to this tutorial only once I had some basic knowledge of python and I actually did learn a lot from it (I was still a bit overwhelmed but not as much as a “True” beginner).

After a discussion with @julien and some friends in the dev community, I think that the current tutorial could be considered as “advanced” or “in-depth” and a (some?) more beginner friendly tutorial in the spirit of the ones from django, fast-api or the official argparse “howto” could be written, and highlighted as an introduction to python with a smoother learning curve.

The Documentation Workgroup might be the right opportunity for it, I’d love to discuss and contribute to this topic and I think there is a lot of awesome things to do to ease python on-boarding as it is introduced to a wider audience of various ages and background!

1 Like

I had a flag about this in my mind but never found the time to tackle it, thanks for raising it!

There’s the hard way and the easy way…

The hard way, I feel we should split the tutorial, but I don’t know how yet, maybe something a newcomer could navigate according to its needs more than something that looks to be aimed to be read like a book, but that’s where in my mind I start mixing “howto” and “tutorial” too much, help appreciated.

The easy way would be to try to enhance the tutorial by small easy steps, easy to merge, and easy to test while teaching: for example it miss a section on functions, I think we can add it. We should also try to simplify some things to ease the reading by a newcomer, for example right on the 2nd page there’s a # -*- coding: cp1252 -*-, I’m no Windows user, but I think this can safely be removed from the tutorial now, and telling about encoding right at page 2 may be intimidating.

1 Like

I think tutorials often have consistent use case that is being worked on through it and sometimes improved/extended in following parts. I wonder if it is even possible to have such an use case/program that using only standard library features would be able to cover satisfiable part of language features and would be consistent and understandable.

It is more natural for libraries and frameworks that specialize in some concrete use cases to find an example and make focused story. I wonder if it is even possible (or even if it’s worth trying) to introduce whole programming language in a similar manner.

As far as I know the Python tutorial, the use cases there are rather short and there are many of them in a single chapters.

Could be (re)written. The main tutorial starts very slow, but then jumps very deep in places (positional only, kw only arguments in functions).

I think some of the more in-depth parts of the tutorial could be split off into the sections of the docs they deal with. The way I read it, there are already a few sections with similar tutorials/howtos (eg asynchio).

I think a significant question is what “context” the tutorial should be written in. Many (good) ones have a focus in mind - Al Sweigart’s Automate focuses a lot on task automation, some of the others on making games, web development, data science etc, and, I think, that ‘goal’ is a part of why those tutorials are compelling.

Secondary idea: after looking at the tutorial a little. Would it be possible to restructure it, with dropdowns ( does this really well) or links to the “more information/more indepth” parts. That may be less fresh writing, and less bike shedding about how much depth is too much, since it becomes more about “should this be above or below the ‘see more’ cutoff”.


I’m a bit more into the hard way described by @julien because the current tutorial does bring value and insights to advanced python users (I often show it to devs with 2+ years of xp and they do learn things from it or deepen their understanding of python standard library).

Currently there are a lot of good usecases ordered in a technical fashion instead of a functional one.
You want to use a list => here’s the API and some small examples in isolation.
Which functionally could be:
You want to manipulate flowers data => Here’s how you can exploit the data with which python feature.

This is great for seasoned developers but it is not what a beginner might be looking for.
We might like to have some basic tutorials on classical use-cases in order to:
1 - Show python potential, concision and clarity
2 - Show people that they can do things and have quick satisfactory results which can be built upon.
3 - Overcome lack of confidence that you experience when you start something new
4 - Overcome modern short attention span (Introduction is nice, ease of access and working example is key)

As exposed by @maciek and @toonarmycaptain, use-cases for an easier tutorial in Python which is generalist might not be as obvious as a tutorial for a specialized library but an acceptable approach might be to have some tutorials with “popular” or “interesting” thematic like data handling (data structure, built-in library (csv), i/o api with file handling…), scientific calculus, small game (with turtle), automation, webscrapping, etc… Once they complete any of the tutorials that better fit the reason why they came learning python in the first place, they can be invited to try building their own project, use a rasberry pi, read the advanced tutorial at their pace or external resources…

About the secondary idea of @toonarmycaptain, I’m not sure to fully understand it but I would see it as an optional “advanced section” going deeper in language feature that would fall back to the tutorial (optional extensions to the tutorial that are not forks but parenthesis). The current tutorial is already quite dense and complete in my opinion :slight_smile: !

We might also want to propose an in browser interpreter (for users struggling with python installation or just wanting to give it a quick try) like the one of or even direct references to such websites.

A subtopic to consider if the idea developed in this topic is considered legitimate is how to qualify such tutorial.

Some idea that already came out while discussing the subject are:

  • Getting in touch with trainers and get feedback from real test sessions.
  • Providing simple feedback opportunity to users:
    • Q&A/forum by chapter or paragraph with quoting option (A bit like video timestamp Q&A on learning platforms)
    • End of chapter/tutorial public feedback form (difficulties, ease of use, understanding, excitement? …)
1 Like

There are many directions the tutorial could go. Perhaps we need to get away from the idea of “the” tutorial. Can we have more than one?

The current tutorial is aimed at programmers coming from other languages (it does not try to explain what a loop is, for example), and it is structured around the constructs of the language. Other possibilities are to structure around tasks or projects.

One of the goals of the documentation working group is to step back from fixing problems with particular pages, and to lay out an overall strategy for the documentation. For example, if we are going to overhaul the tutorial, who should the audience be? Should there be more than one? Should tutorial(s) focus on particular problem domain(s), or should they stay generic and focus on language features?

The devguide has a section covering tone and voice of the documentation, but it’s applied unevenly. Mostly, these kinds of decisions about the documentation are currently made individually for each page and are up to the original author of the page. The problem is even harder for the tutorial because of its size: changing the audience, tone, or approach is a large change to a number of pages.


I am a noob. I so badly wanna learn Python. As the original poster said, I do find it overwhelming. What would help me is small projects which I can work on and then graduate into bigger ones.

Basically I mean footnotes, but interactively, via dropdowns or popup boxes (so you might have a highlighted word, asterisk, or superscript that, when clicked, dropped down some more explanatory text, or popped up a box). My inital example would be that a new user doesn’t necessarily need to know about kw-only or positional-only args.

I would assume it’s clear that multitude a swarm of different tutorials with different levels/foci/voices is better than just one.

I think a high view question is what the psf/python docs/core team should be providing (and committing to maintaining and extending).

At the moment, the main feature is a tutorial that’s been described as a bridge from other languages, for users with some fluency in programming concepts and computer science in general.

Should there be an ‘official’ “intro to coding level” tutorial for python?
As @illllm’s question illustrates, this is desired by users. The scope and form of such a tutorial, were the Group to decide to take it on, is up for discussion. The range goes from simple “here’s how to write code, in python” all the way to extensive material, guided projects, challenges, etc.

While I love for such resources to exist, outside of a basic/introductory level introduction to python syntax/coding concepts, I’d leave (and link to) the course-style python education to third parties.

I would not be disappointed if the PSF were to parent or support an organisation with “python education” as it’s core focus. I don’t know if there is an FOSS org similar to codecademy or that takes contributions already? If there is something FOSS, particularly a platform that takes “here’s my turtle tutorial”, “here’s my python class inheritance/composition tutorial” sort of content, I question whether it would be better to push efforts towards such a platform, rather than accumulating more maintenance burden (and potential constant PRs/bikeshedding therein) with expanding the mission of the tutorials colocated with the docs.

Another consideration:
Someone probably has the data, but @pgalvan mentions the technical, rather than more narrative (my word) nature of the docs. My question/hypothesis is whether the majority of traffic is coming to the current tutorial via google search for specific topics (I know it is from my usage) as opposed to from pages within the tutorial, and from ‘previous’ pages where people are working/reading through the tutorial, rather than jumping around from concepts they’ve googled (me).

I posit that the usage is more of a reference than a body that’s worked through linearly. This might inform how modifying or supplementing what’s currently there is approached.
At the moment I figure a lot of the tutorial is accessed as a more readable reference than the main docs, which then referred to from the tutorial, in my personal experience.

I worked through a lot of, if that helps, walks you through some small projects. A google search for “beginner python project ideas” brings up a lot of results.

I fully agree.
I don’t think the core dev team is a good team to maintain a beginners’ tutorial to Python. Such a tutorial should not live in the CPython repository, and should not be maintained by CPython maintainers. And should not be discussed in the Core Development category on Discord, but that’s a detail :‍)
It should definitely exist somewhere, though!

The current tutorial has a scope that can be maintained by core devs (with kind help from documentarians). It also does serve a purpose as it is, but it’s not what many people want in a tutorial.
For instance, it only describes Python, not additional libraries (which you’ll probably need for data analysis or web scraping), alternate implementations of Python, or services (like pythontutor). This independence is great for maintenance; tying the docs to CPython versions only makes them age quite well.

Not one, I’m afraid. The way you should learn depends on what you want to achieve and what you already know. It’s good that there’s the current tutorial and Automate the Boring Stuff and , say, Software Carpentry lessons for scientists.


FWIW I didn’t exclusively mean the core devs working on CPython core, presumably the majority of the maintenance work would be by members of the Docs WG and other contributors. If I understand rightly, one of the goals of the WG should be to bring in more people to help maintain the docs/tutorials, with core devs providing oversight from a technical accuracy perspective, rather editorial or pedagogical.

Yeah when I come back, I look for a Documentation category, but it’s not there.