How to Teach Beginners to Read Python Documentation
I ran a small test at club last February because I was tired of a specific pattern. Fourteen students, all of whom had written at least two hundred lines of Python, and a single question on a slip of paper: what does the second argument of...

I ran a small test at club last February because I was tired of a specific pattern. Fourteen students, all of whom had written at least two hundred lines of Python, and a single question on a slip of paper: what does the second argument of str.split do? I did not let them run code. Nine of them wrote some version of I would search for it. Two guessed. Three got it right, and all three had been coding for more than a year.
Not one of them thought to open the documentation, even though the page answering that question has existed, unchanged in substance, for over a decade. That is not laziness. It is that nobody had ever sat with them while they read a doc page, and the pages look like a wall of notation if you have never had the notation explained. Teaching this is the single highest leverage hour I spend with a group, and it takes about three sessions to stick.
Why beginners avoid documentation, specifically
When I ask students what stops them, the answers cluster. The top one, every time, is that they do not know what they are looking at. A function signature is a compressed language, and nobody teaches it. A page that opens with brackets, asterisks and a bare slash reads as hostile.
The second reason is that a forum answer gives you code you can paste, and the docs give you a description you have to convert into code yourself. That conversion step is work, and a student who is forty minutes into a problem at 9pm will take the paste every time. I do not blame them for that choice; I try to make the docs faster than the alternative so the choice changes.
The third reason is quieter and matters more. Many beginners believe documentation is written for professionals and that needing it means they are behind. One student told me she assumed the docs were the thing you read after you already knew the answer. That belief has to be named out loud, or no amount of practice will dislodge it.
Teach the notation before anything else
I spend the first twenty minutes on nothing but how to read a signature, with no coding at all. This is the table I put on the screen, built from the five or six symbols that actually cause confusion.
| What you see | What it means | Example from the standard library |
|---|---|---|
| Square brackets around an argument | Optional; there is a default you can ignore | list.pop([i]) removes the last item if you pass nothing |
| A bare slash in the argument list | Everything before it must be passed by position, not by name | sorted(iterable, /...) so you cannot write iterable equals |
| A bare asterisk in the argument list | Everything after it must be passed by name | sorted(..., *, key=None, reverse=False) |
| Asterisk attached to a name | Accepts any number of extra positional arguments | print(*objects, sep=' ') |
| An arrow after the brackets | The type of thing you get back | A method documented as returning a list, not printing one |
| A word in italics in the prose | A term defined in the glossary, usually iterable or sequence | Iterable means anything you can loop over, not only a list |
Then I give them four signatures cold, with the prose hidden, and ask them to write down one legal call and one illegal call for each. The ones I use are sorted, dict.get, random.sample and str.split. The illegal call is the half that teaches, because getting it wrong produces a specific error they will later recognise, and recognising the error is the loop closing.
The advice I think is wrong
The standard recommendation is to send beginners to the official tutorial. I have stopped doing it, and I think it holds people back.
The tutorial is a good document written for someone who already programs in another language and wants Python. A beginner reading it from the top gets chapters on modules and virtual environments before they have a reason to care, and the experience teaches them that documentation is long and mostly irrelevant to their problem. That is exactly the lesson I am trying to prevent.
What works instead is the library reference, entered sideways, for a function the student is using right now. Not read, searched. Open the page for the thing in their hands, find the four lines that answer the question, close the page. Three minutes, not thirty. After about a dozen of those a student stops seeing the docs as a textbook and starts seeing them as a lookup, which is what they are.
I will add one honest caveat, because the picture is not clean. Some library pages genuinely are bad for beginners, and the regular expression module is the clearest example. When a page is written for implementers rather than users, say so out loud rather than letting the student conclude they are the problem. I tell my groups that roughly one page in six is written by someone who forgot a beginner would read it.
The rule that changed my club nights
Here is the mechanic I use, and it is the only part of this I would call non obvious. When a student raises a hand with a question that documentation can answer, I do not answer it and I do not say read the docs. I say ninety seconds, and I set a visible timer.
They open the page. If they find it, they explain it back to me in their own words, which takes about fifteen seconds and does more for retention than my explanation would. If the timer runs out, they get the answer with no friction and no comment, and then we look at the page together so they can see where it was hiding.
The timer matters because the thing beginners are actually afraid of is unbounded effort. An open ended instruction to go read something feels like being sent away. Ninety seconds is obviously survivable, and the cap removes the fear of wasting the evening. Mentors need the discipline here more than the students do, and if you are bringing in volunteers it is worth agreeing this before the first session, the same way you would agree on how much of a bug to fix for someone.
One measurable change: in the autumn term before I started this, mentors answered roughly 40 lookup questions a night across 14 students. By the fourth week of doing it, that number was under 15, and the questions that remained were better ones. The students were not getting less help. They were spending it on things documentation cannot do.
What the three sessions look like
Session one is notation, as above, with no computer open for the first twenty minutes. Session two is a scavenger hunt: six questions that each need exactly one doc page, run in pairs, with the pair writing the answer plus the page title. Mine includes how to sort a list of names ignoring case, how to get a value from a dictionary without an error when the key is missing, and how to pick three random items without repeats.
Session three is the one people skip and it is the one that transfers. Give them a function nobody in the room has used, something like itertools.groupby or str.maketrans, and ask them to use it correctly on the first try with only the docs. Half will fail. That is fine, because the failure is now about a hard function rather than about a scary page, and the habit of decomposing the problem before reaching for a tool is the same habit you train when you teach them to break a problem into small steps.
After that it is maintenance. I keep a browser tab with the library reference open on the projector all evening, so the docs are visibly part of the room rather than somewhere you go when you are stuck.
FAQ
At what level should I introduce documentation?
Earlier than feels right, once a student is calling functions someone else wrote and has hit one argument they did not expect. For most of my groups that is four to six weeks in. Waiting until they are intermediate means fighting a search engine habit that has had a year to set.
Should I teach the help function in the REPL instead?
Teach both, in that order. help() shows the same text with less navigation, so it is a gentler first exposure, and it works offline. Move to the web pages once they need the examples sections, which help() often does not include.
What about students who only read AI answers?
Let them, then ask for the source. An assistant that cannot name the page it is paraphrasing has given them something unverifiable, and checking it against the real signature takes fifteen seconds. The skill I want is verification, not abstinence.
Does any of this help with error messages?
It helps a lot, because many errors are a signature violation described in different words. A student who understands what a bare asterisk means stops being baffled by a message about keyword only arguments, which pairs directly with teaching them to read an error message calmly.
More in Teaching Code
Teaching Code
How to Teach the Difference Between print and return
In week five of our adult evening group, a learner called me over because her code had stopped working.
Teaching Code
How to Train Volunteer Mentors for a Coding Club
Our club recruited nine volunteers in one term. Three were still turning up by week six.
Teaching Code
Trace Tables: Teaching Beginners to Run Code on Paper
A student shows me a loop that should add the numbers from 1 to 10 and prints 45 instead of 55.