Hacker News Reader

Comment by graue | Hacker News Reader

I love how there's a thorough "what's new" document for a still-in-progress release, and terms like "provisional API" are linked to a glossary that tells you exactly what they mean. While Python is not the most interesting language to me anymore, it still sets the standard in clear, comprehensive, newbie-friendly documentation.

View on HN

I think newbies are far from the people most likely to be looking at version-to-version changelogs in any language.

This is great for those maintaining substantial codebases in the language, though.

The thorough specification process gives lots of warning for the introduction of changes (so you can almost update on release day if you were really so inclined and prepared).

Edit: Though on a re-read, clear, comprehensive newbie friendly documentation is something that (somewhat unrelatedly) Python does have. My bad.

I'm by no means a programming newbie, so maybe this skews what I'm about to say, but I find that reviewing release notes and changelogs is often quite useful while I'm still in the belly of a learning curve. If the project in question has a cohesive vision (big "if"), this can help frame the trajectory of that vision and get you to march in step with the project's state of the art more quickly.

Even I was amazed at the neat documentation of the changes that are made for this release. There is some unknown familiarity in that page layout that my brain naturally knows what to click and read through. Kudos to team who did this work.

Reply on news.ycombinator.com