Reading official docs well

Why this matters

When a program does something you did not expect, the most reliable answer is often in the official documentation. The documentation, or docs, is a set of pages written by the people who make the program. The pages describe each feature, what it accepts, and what it returns.

Beginners often search for an answer and land on a blog post from several years ago, or a forum answer about a different version of the tool. That post may be right, or it may describe a feature that has since changed. Official docs are slower to read, but they are the source. This lesson covers the parts of a docs site, how to search it, how to read an example safely, and how to check the version before you rely on a page.

The teach-back lesson earlier in this module shows how to check your own understanding after you read a page. The reading errors lesson shows how to read the error message that often sends you to the docs in the first place.

The idea, built step by step

Step 1: Know what each part of a docs site is for

Most official docs sites have the same parts, though the names differ from one tool to the next:

• A tutorial or getting started page teaches a path in order. Use it when you are new to a tool.
• A guide or how-to page answers one task, such as reading a file. Use it when you know the task you want to do.
• A reference page lists each function, method or setting, with its exact rules. Use it when you need the precise details.
• A changelog, release notes or what's new page lists what changed in each version. Use it when a feature behaves differently from what you read.
• A search box and a version selector appear on most pages. The selector is a dropdown, or a version number in the web address.

Python's documentation is a good example. It has a tutorial for beginners, a library reference that describes the built-in functions and the standard modules, and a language reference that describes the grammar and rules of the language itself. A beginner reads the tutorial first. An engineer who needs the exact behaviour of one string method goes to the library reference.

A simple rule helps. If your question is "how do I learn this", use the tutorial. If your question is "what exactly does this do", use the reference. If your question is "why does this behave differently now", use the release notes.

Step 2: Search for the exact name

Search boxes match words. Use the name the docs use, not a description of what you want. If you search for "remove the start of a string", you get a long list of pages that mention the words. If you search for removeprefix, you get the page for that one method.

Here is a worked example. You have the version string "v2.1" and you want 2.1. The method you need is called removeprefix, and it belongs to the str type, which is Python's type for text. Python's reference describes it, and the same description is available on your own machine. pydoc is the help tool that comes with Python, and this command prints it:

python3 -m pydoc str.removeprefix

The output starts like this:

Help on method descriptor removeprefix in str:
 
str.removeprefix = removeprefix(self, prefix, /) unbound builtins.str method
    Return a str with the given prefix string removed if present.
 
    If the string starts with the prefix string, return string[len(prefix):].
    Otherwise, return a copy of the original string.

Read it in parts. The first line names what you are looking at. The line with removeprefix(self, prefix, /) is the signature, which lists the inputs. It takes one input, called prefix. The paragraph after it states the rule in two cases. If the text starts with the prefix, the prefix is removed. Otherwise, the text comes back unchanged. A reader who only skims the first line might guess that the method always removes something. The second case is the part that prevents bugs.

Now use it:

version = "v2.1"
print(version.removeprefix("v"))
print("2.1".removeprefix("v"))

Save this as version.py and run it:

python3 version.py

Output:

2.1
2.1

The first line removes the v. The second line has no v to remove, so the text comes back unchanged. That is exactly the rule the docs stated.

Compare this with a guess that many beginners make. They drop the first character with a slice, which takes everything from position 1 onward:

print("v2.1"[1:])
print("2.1"[1:])

Output:

2.1
.1

The first line is right by luck, because the first character happens to be the v. The second line removes the 2, which is wrong. A slice removes characters by position, and removeprefix removes text by content. The docs name the second behaviour, and the slice does not have it.

Step 3: Read the example, then run it yourself

Docs examples are short and clean. They usually leave out the import lines, the file setup and the error cases. Before you copy an example, check four things:

1. Imports. Does the example use a module (a file of ready-made code, such as math) that you must import first? If you do not, Python raises a NameError.
2. Inputs. What values does the example use? Change one value and predict the new result before you run it.
3. Output. The output shown is what the author ran, on the version the author used. Your output can differ if your version is different.
4. Prompts. Interactive examples show >>> at the start of lines typed into Python's interactive prompt. The >>> is not part of the code. Copy only the typed part.

A harder example uses the math module. The reference page for math.sqrt says it returns the square root of a number. Read the official description on your machine:

python3 -m pydoc math.sqrt

The output starts like this:

Help on built-in function sqrt in math:
 
math.sqrt = sqrt(x, /)
    Return the square root of x.

Now try the example in a new file without the import line:

print(math.sqrt(4))

Run it:

python3 sqrt_no_import.py

Output:

Traceback (most recent call last):
  File "/home/chiranjeet/dev/anisha/scratch-offtmp/claude-review-06/sqrt_no_import.py", line 1, in <module>
    print(math.sqrt(4))
          ^^^^
NameError: name 'math' is not defined. Did you forget to import 'math'?

The message says what to do. Add import math on the first line, and the program prints 2.0. Python prints the full path of the file in the first line of the traceback, so your path will differ.

Next, try a value the docs do not show in this short description. A square root of a negative number is outside the normal range for this function. Save this file as sqrt_negative.py:

import math
print(math.sqrt(-1))

Output:

Traceback (most recent call last):
  File "/home/chiranjeet/dev/anisha/scratch-offtmp/claude-review-06/sqrt_negative.py", line 2, in <module>
    print(math.sqrt(-1))
          ~~~~~~~~~^^^^
ValueError: expected a nonnegative input, got -1.0

The short description does not mention negative numbers. The error does. When an error and a docs page disagree or stay silent, the error is evidence of a rule, and the reference page or a search for the error text can confirm it.

A method with optional settings

The third example has more moving parts. Many methods take optional settings that have default values. The reference shows them in the signature, which is the line with the method name and its inputs. Take str.split. Its signature in the pydoc output is:

str.split = split(self, /, sep=None, maxsplit=-1)

Read it in three parts. sep is an optional input. If you leave it out, it is None. maxsplit is also optional, and its default -1 means there is no limit on the number of splits. The description then explains sep: when it is None, the method splits on any run of whitespace, and it drops the empty pieces. Now the examples that the signature and the description predict:

print("a,b,c".split(","))
print("a,b,c".split(",", 1))
print("a b  c".split())

Output:

['a', 'b', 'c']
['a', 'b,c']
['a', 'b', 'c']

The first line gives sep the value ",". The second line gives a second input, which the signature places in the maxsplit position, and that allows only one split, so b,c stays together. The third line gives no input, so sep is None. The two spaces in "a b c" count the same as one, and the method returns three words.

Reading the signature is the step that beginners skip. A beginner who reads only the first line of the description might pass a number as the first input:

print("a,b,c".split(1))

Save this as split_wrong.py and run it:

python3 split_wrong.py

Output:

Traceback (most recent call last):
  File "/home/chiranjeet/dev/anisha/scratch-offtmp/claude-review-06/split_wrong.py", line 1, in <module>
    print("a,b,c".split(1))
          ~~~~~~~~~~~~~^^^
TypeError: must be str or None, not int

The first input is the separator, and a separator must be text or None. The error repeats the rule that the signature states. The fix is to read the signature before you guess the order of the inputs.

Step 4: Check the version number

Every docs page describes one version of a tool. A feature may be missing in an older version, or it may behave differently in a newer one. Check the version in three places:

1. The version on your machine. For Python, run python3 --version. For Node, run node --version. On the machine used to test this lesson, the output was Python 3.14.4 for Python and v24.20.0 for Node.
2. The version selector on the docs page, or the version number in the page address. Pick the version that matches your machine.
3. Notes on the page. Many reference entries include a line such as "New in version 3.9" or "Changed in version 3.x". Read the note against your version.

Here is a check you can run inside Python itself:

python3 -c "import sys; print(sys.version_info[:2], sys.version_info >= (3, 9))"

Output on the test machine:

(3, 14) True

sys.version_info is a tuple, which is an ordered group of values. Here it holds the major version and the minor version. Comparing two tuples goes item by item. (3, 14) >= (3, 9) is True because the first items are equal (3 and 3), and then 14 is greater than 9. This tells you that removeprefix, which the reference marks as new in Python 3.9, is available on this machine.

Node has the same kind of check. Methods exist or they do not, and you can test for one directly:

node -e "console.log(typeof Array.prototype.toSorted)"

Output:

function

If the output were undefined, the method would not exist in that Node version, and the docs for your version would be the ones to read.

When the docs and your machine disagree, you have two choices. You can read the docs for the version you have, which is the safer choice. Or you can upgrade the tool, which gives you the newer feature but can change other behaviour that your existing programs rely on. The first choice costs nothing but reading time. The second can break code that worked yesterday. A reference marked "new in version 3.9" means that on an older Python, a line such as "abc".removeprefix("a") fails with an AttributeError, which says the text has no such attribute. The version check tells you before you run the line.

Common mistakes

Searching with a description. A description returns many pages that use the same words in different ways. Search for the name. If you do not know the name, search the docs for a related term, then look at the names listed on the page.

Trusting a blog post over the reference. The post may have been written for an older version, or it may guess at behaviour the reference describes exactly. When a post and the reference disagree, follow the reference for your version and treat the post as a lead.

Copying the prompt markers. An example from an interactive session looks like this:

>>> "abc".removeprefix("a")
'bc'

If you paste the whole block into a file, Python fails on the first line. Here is the result when the block is saved as docs_copy.py and run:

  File "/home/chiranjeet/dev/anisha/scratch-offtmp/claude-review-06/docs_copy.py", line 1
    >>> "abc".removeprefix("a")
    ^^
SyntaxError: invalid syntax

Copy only the code after >>>. The fix is one line:

print("abc".removeprefix("a"))

Output: bc.

Forgetting the import. The math example above shows the error. The fix is to read the example's first lines, or the module's page, and add the import.

Typing the name wrong. A misspelled name raises an error that often suggests the right name. Here is a misspelled call run with python3 -c:

python3 -c "print('abc'.removeprefx('a'))"

Output:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    print('abc'.removeprefx('a'))
          ^^^^^^^^^^^^^^^^^
AttributeError: 'str' object has no attribute 'removeprefx'. Did you mean: 'removeprefix'?

The suggestion in the message is the name to search for in the docs. Read the suggestion before you search again.

Ignoring the version. A correct example on a new version can fail on an old one. The check in step 4 takes one line, so run it before you spend an hour on a version mismatch.

Practice

Exercise 1. Use pydoc to read the description of str.startswith. What does the method return?

Show the answer

Run python3 -m pydoc str.startswith. The description says it returns True if the string starts with the given prefix, and False otherwise. Check it yourself with python3 -c "print('abc'.startswith('a'))", which prints True.

Exercise 2. Write one line of Python that prints True if your Python version is 3.9 or newer, and False otherwise.

Show the answer

Use python3 -c "import sys; print(sys.version_info >= (3, 9))". On the test machine it printed True. On a machine with an older Python it prints False.

Exercise 3. The docs example >>> "abc".removeprefix("a") fails when pasted into a file. Change it so the file runs and prints bc.

Show the answer

Save this as docs_fixed.py:

print("abc".removeprefix("a"))

Run it with python3 docs_fixed.py. Output: bc. The >>> marker is removed, and print shows the value, because a file does not print the value of a bare expression.

Exercise 4. Explain why "2.1"[1:] gives .1, and why "2.1".removeprefix("v") gives 2.1.

Show the answer

A slice removes characters by position. [1:] means "start at position 1", which is the second character, so the 2 is dropped. removeprefix removes text only when the text starts with the prefix. The string "2.1" does not start with v, so nothing is removed and the original text comes back.

Exercise 5. Run python3 -m pydoc math.sqrt and find the one-line description. Then write a file that calls math.sqrt with a negative number, run it, and write down the error message.

Show the answer

The description is "Return the square root of x." The file import math followed by print(math.sqrt(-1)) fails with ValueError: expected a nonnegative input, got -1.0. The description does not mention negative numbers, so the error message is the only place where the rule shows. Keep the error message as a note, and search the reference for "nonnegative" if you want the full rule.

Summary

• Pick the part of a docs site that matches your question: tutorial, reference or release notes.
• Search for the exact name of the feature, and read the rule stated in its description.
• Before copying an example, check its imports, its inputs and any >>> prompt markers.
• Check your installed version against the docs version and the notes on the page.
• When an error message names a different word, search for that word.