What is PyNotes?

PyNotes is a side project I’ve been gradually building to document Python in a systematic way. The goal is to create a comprehensive reference covering three main areas:

  • Python Enhancement Proposals (PEPs): The proposals that shape how Python evolves
  • Python Standard Library: The modules and packages that come with Python
  • Official Python Tutorial: A walkthrough of Python’s core concepts

The site lives at pynotes.bjdean.id.au and follows a consistent format for each article: a TL;DR summary, an “Interesting!” callout highlighting something noteworthy, and bite-sized sections with practical code examples.

Why Document Python?

As a sort of excercise - I’ve use python extensively but there was always going to be some part of the language or some library I’ve not seen or needed and this was a good way to go for a “personal deep dive” while buiding up some useful documentation along the way. It’s a collaborative excercise between me and Claude Code. I start by randomly sampling topics I’ve not written about yet, choose somthing that seems like an interesting topic and build from there.

My aim is to build articles that are short and example-led while covering concepts such as:

  • Providing context: Why was this feature added? What problem does it solve?
  • Showing practical examples: Real-world code that demonstrates the feature in action
  • Highlighting the interesting bits: What makes this particular feature worth knowing about?
  • Creating a learning path: A structured way to explore Python’s capabilities systematically

Progress to Date

As of today, PyNotes has 85 published articles covering a mix of all three content areas (PEPs, the standard library and python tutorials).

The Writing Process

Each article follows a template that keeps them consistent:

  1. TL;DR: Two to three sentences that answer “what is this and why should I care?”
  2. Interesting!: One standout feature or use case that makes the topic worth exploring
  3. Structured sections: Breaking down the topic into digestible chunks
  4. Code examples: Showing before/after comparisons or practical usage patterns
  5. Reference link: Back to the official documentation

This structure emerged through trial and error. Early articles were sometimes too comprehensive (trying to replicate the entire official documentation) or too shallow (just scratching the surface). The current format seems to hit a sweet spot - detailed enough to be useful, concise enough to be readable.

The articles also use Python code validation to ensure examples actually work. There’s nothing worse than documentation with broken examples.

Ideas for the Future

The immediate goal is to finish with at least one article per PEP, the standard library and python tutorial.

Beyond that, some ideas I’m considering:

Cross-linking and themes: Once there’s critical mass of content, it could be interesting to group related articles. For example, linking all the typing-related PEPs together (PEP 484, 526, 544, 585, 604, 612) or showing how async programming evolved (PEP 3156, 492, 525, 530).

Practical guides: Going beyond individual features to show how they work together. For instance, “Building a CLI tool with argparse, pathlib, and logging” or “API client best practices with asyncio, aiohttp, and typing”.

Python version timelines: Showing when features were introduced and how they build on each other. Understanding that f-strings (PEP 498) came after str.format() helps contextualize why Python has multiple string formatting approaches.

Interactive examples: The current code examples are static. It might be interesting to embed interactive Python consoles using something like Pyodide to let readers experiment with the examples directly.

Reflections

Building PyNotes has been a valuable experience. The act of documenting forces deeper understanding (just like explaining the topic to someone else) and in fact in some cases discussing/reviewing an article with Claude Code has provided the same sort of benefits.

Closing Thoughts

PyNotes remains a work in progress and for me the value isn’t just in completion but in the ongoing process of exploring and documenting Python’s capabilities. Each article adds to a growing reference that’s useful both for learning new features and refreshing knowledge of familiar ones.

If this is of interest to you, check out pynotes.bjdean.id.au. And if you’re working on similar projects (documenting a language, library, or framework), I’d be interested to hear about your approach and what you’ve learned.

Reference: PyNotes - Python Documentation