STR Coding Club logo STR Coding ClubLearn to code, together
Teaching Code

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...

A laptop showing a Python library reference page beside a printed sheet of function signatures with notes

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 seeWhat it meansExample from the standard library
Square brackets around an argumentOptional; there is a default you can ignorelist.pop([i]) removes the last item if you pass nothing
A bare slash in the argument listEverything before it must be passed by position, not by namesorted(iterable, /...) so you cannot write iterable equals
A bare asterisk in the argument listEverything after it must be passed by namesorted(..., *, key=None, reverse=False)
Asterisk attached to a nameAccepts any number of extra positional argumentsprint(*objects, sep=' ')
An arrow after the bracketsThe type of thing you get backA method documented as returning a list, not printing one
A word in italics in the proseA term defined in the glossary, usually iterable or sequenceIterable 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.

SD
Selene Dragomir

Selene coaches students for programming contests. She writes about practice problems, debugging and the habits that help beginners get unstuck on their own.

More posts by Selene

More in Teaching Code

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto