Skip to content

Reading documentation

~13 min

In short

Official documentation is slower to read than a blog post, and usually more correct. This is the most useful skill in this section. This page shows where the official docs live, how to read a single entry, how to use man and help() from the terminal, how to read a README, how to search, and how to ask a question that gets a useful answer.

Where the official docs are

Each language and tool has an official site. For Python, the top page at docs.python.org/3/ has these sections [1]:

  • Tutorial: "Start here: a tour of Python's syntax and features."
  • Library reference: "Standard library modules."
  • Language reference: syntax and language elements.
  • Built-ins reference: built-in functions and classes.

Read the tutorial once from start to finish. Use the library reference as a lookup book after that.

The Python version matters. The docs site shows the newest release by default. Check your version with python3 --version, and use the matching path, such as docs.python.org/3.12/, when they differ.

How to read one entry

Take str.split, the method that cuts a string into pieces. The library reference gives it a short entry with four parts [2]. Here are the parts, using the 3.12 documentation:

str.split(sep=None, maxsplit=-1)
    Return a list of the words in the string, using sep as the delimiter string.
    ...
    >>> '1,2,,3,'.split(',')
    ['1', '2', '', '3', '']
  1. The signature shows the name and the arguments. Arguments in brackets, or with a default such as sep=None, are optional.
  2. The description says what the function returns and what each argument does.
  3. The examples show real output. Read them before you run anything, and copy one into the REPL to check.
  4. Notes and related entries warn about edge cases. The split entry says that consecutive separators give empty strings between them [2].

The example above shows what you would expect from the description. Empty strings appear wherever two separators touch.

Use help() and man in the terminal

You do not need a browser to check a detail. help() shows the documentation built into Python. It takes an object or a name as its argument [3]:

$ python3 -I -c "help(str.split)" | head -4
Help on method descriptor split:

split(self, /, sep=None, maxsplit=-1) unbound builtins.str method
    Return a list of the substrings in the string, using sep as the separator string.

This output is the built-in docstring. It is shorter than the web page, and the wording differs slightly (it says "substrings" where the web page says "words"). Both describe the same method. When the two disagree, trust the web page for the version you have installed.

For command-line tools, man opens the manual page [4]. The section numbers matter. Section 1 is user commands, 2 is system calls, 3 is library functions, and 5 is file formats [4]. One name can appear in more than one section, so give the number when you need a specific one. For example, man 2 write shows the system call, which is the page you need for the machine page. Use man -f word to search one-line descriptions.

Read a README

A README is a file that GitHub displays on a repository's front page, and it is often the first thing a visitor reads [5]. Read it in this order:

  1. What the project does, in one or two sentences.
  2. How to install it. Look for commands you can copy.
  3. How to run it, with a small example.
  4. Where to get help, such as an issue tracker.
  5. The license, which says what you may do with the code.

If the README is missing or does not say how to run the project, that is a clue about the project, not your failure to understand.

Search effectively

Use the words the tool itself uses. Paste the exact error message in quotes, with the tool name and version. Add site:docs.python.org or site:git-scm.com to the search to focus on official pages. Start with the official docs and then read a second source. Check the date of any answer, because old answers may describe old versions.

Ask a good question

When you have looked and still have no answer, ask someone. A good question makes it easy to help. These habits matter most [6]:

  • A specific title. "Python ZeroDivisionError in average()" is useful. "Help with Python" is not.
  • A minimal example. Remove everything that does not matter until the problem is small and complete. Paste that code. Someone should be able to copy it and see the bug [6].
  • The exact error. Copy the error text as it appears. Do not retype it, because small changes make it harder to search.
  • What you have tried. Say what you searched for and which docs you read. It saves time for the helper and shows you did the work [6].

Here is a question template:

Title: Python ZeroDivisionError in average() when list is empty

Goal: compute the average of a list of scores.

Code (minimal):
    def average(nums):
        return sum(nums) / len(nums)
    print(average([]))

Error (exact):
    ZeroDivisionError: division by zero

Tried: read the Python docs on sum() and len(); confirmed len([]) is 0.
Question: what is the right way to handle an empty list here?

Check it with Python

The runnable block below checks a few statements from the docs. Each assert is a claim you can test. If an assert fails, the docs and your idea do not agree.

assert "a,b,,c".split(",") == ["a", "b", "", "c"]
assert "  padded  ".strip() == "padded"
assert "a b".split() == ["a", "b"]
assert "substrings" in str.split.__doc__
assert callable(help)

Try this

  1. Run python3 -I -c "help(str.split)" and compare the output with the library reference entry.
  2. Pick a README from a project you use, and write down its install and run commands.
  3. Write one question about a bug you hit this week, using the template above, and check whether a search answers it first.

Sources

  • [1] Python 3 documentation, index. https://docs.python.org/3/
  • [2] Python 3.12 documentation, "Built-in Types" (str.split). https://docs.python.org/3.12/library/stdtypes.html
  • [3] Python 3.12 documentation, "Built-in Functions" (help). https://docs.python.org/3.12/library/functions.html
  • [4] man(1), Linux man-pages. https://man7.org/linux/man-pages/man1/man.1.html
  • [5] GitHub Docs, "About READMEs". https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
  • [6] freeCodeCamp, "How to ask good technical questions". https://www.freecodecamp.org/news/how-to-ask-good-technical-questions/