Language Documentation

Over the years I’ve learned about the importance of (official) documentation, and in fact it’s my preferred method of learning something programming related.

It’s very obvious though, that some frameworks and languages’ documentation are not all created equal.

This might be a hot take, but I think Python’s documentation are poor (docs.python.org). Often times, I have found the documentation for most modules to be very poorly structured, and it almost felt as if you had to read the entire documentation page to really make any sense of it. An example of what good Python documentation should be like is from “Real Python” (https://realpython.com/). Usually I’d go there for a good overhead view of a particular technique/module, then dive into Python’s docs.

But for Python being such a great language for beginners, I find the documentation not so, and it’s a pity because beginners should learn to read documentation as soon as possible in my humble opinion. Unless I’m reading the wrong docs, please point me to some more well structured and clearly written Python docs.

I’ve been reading and learning some Phoenix LiveView recently, and I think for the most part I do appreciate hexdocs (https://hexdocs.pm/), especially for the main modules used in Phoenix.

Another set of docs that I particularly liked reading, are the Nextjs and Remix docs (https://nextjs.org/docs/getting-started and https://remix.run/docs/en/v1 respectively). Especially the Remix docs, as I really enjoy the aesthetic appeal of the docs page. Of course it’s a bit different scope and context than Python & Elixir (framework vs language).

To end this post with another side-thought: some say the best documentation should be the code, and more and more I appreciate this when working with JavaScript (more specifically Typescript) because I rely heavily on the language server to point me to the actual source code of a particular library or node module. I actually love this so much, I feel like its been a big hit on my productivity on my Phoenix/LiveView journey as the language server I’m using with Neovim doesn’t seem to be working as well.

In any case, let’s keep reading docs everyone.