comparing language documentation

february 18, 2021

The most important thing and yet the most undervalued thing for programming languages (and software in general) is clear, consistent documentation. If a language doesn’t set a good example for good documentation, then it seems that the developers in that language follow its example. This is a short post, but we’re going to compare a few programming languages against my preferences for documentation.

nytpu’s criterion for determining whether a language is worth it to use or not and also a measure of whether the language designers care about the developers that use it

A language’s documentation should meet half of these ten requirements:

• Most/all documentation is available offline (officially, something like zeal doesn’t count)
• Most/all documentation is available without a web browser
• If it does require a web browser, it is viewable in a terminal browser like lynx
• The documentation is well-organized and easily browsable
• Bonus points if third party libraries can easily add their documentation to the offline documentation source
• The language has a clear, consistent specification that anyone can read
• The language has a formal specification at all
• If there is no specification, the reference implementation is easily readable and understandable
• Bonus points for the reference implementation being hackable
• The standard library (or equivalent) has complete documentation

Some are more important than others, but we’re just going to go with 5/10 to make it easy to judge. N/A’s count as a point because if something like a browser isn’t required at all the point for being viewable in lynx is moot, so it gets both.

looking at languages

rust

Ordinarily I wouldn’t even give rust the time of day, but it does so abysmally I had to share:

• Most/all documentation is available offline (officially, something like zeal doesn’t count)

Yes, with rustdoc. It’s mostly for generating documentation for local projects, but I believe it has a copy of the std docs too.

• Most/all documentation is available without a web browser

Nope.

• If it does require a web browser, it is viewable in a terminal browser like lynx

Absolutely not.

(282.5kib) really wonderful rust, really readable

• The documentation is well-organized and easily browsable

I don’t use it regularly (obviously), but clicking around the std docs it seems incoherent sometimes.

• Bonus points if third party libraries can easily add their documentation to the offline documentation source

Yes, I believe the aforementioned rustdoc can generate documentation for installed libraries^Wcrates.

• The language has a clear, consistent specification that anyone can read

No.

• The language has a formal specification at all

Nope! Something silly like a specification is for the boomer developers, we’re cool and hip! We write code and change functionality as we please! Who needs a stable language when you have //////memory safety//////!!!!!!!!!!!!!!!!!!!!!!!!!

• If there is no specification, the reference implementation is easily readable and understandable

Nope, >350,000 lines of difficult to understand code.

• Bonus points for the reference implementation being hackable

Absolutely not, even compiling it yourself is a bitch.

• The standard library (or equivalent) has complete documentation

Yes, via rustdoc.

So, rust meets 3/10, it fails by any standard. Disappointed, but not surprised. The only decent part is offline rustdoc but even that’s just directly ripped off from godoc, but shittier. (you have to write markdown code comments‽ WTF‽)

c

• Most/all documentation is available offline (officially, something like zeal doesn’t count)

Yes, man pages.

• Most/all documentation is available without a web browser

Yes.

• If it does require a web browser, it is viewable in a terminal browser like lynx

N/A.

• The documentation is well-organized and easily browsable

Ehhh, not really. If you know what function you’re looking for man pages are good, but if you don’t know what header or function to use it can be hard.

• Bonus points if third party libraries can easily add their documentation to the offline documentation source

Yes, it’s trivial to add new man pages.

• The language has a clear, consistent specification that anyone can read

No, the standard isn’t particularly useful to anyone other than compiler devs.

• The language has a formal specification at all

Yep!

• If there is no specification, the reference implementation is easily readable and understandable

No official reference implementation. N/A.

• Bonus points for the reference implementation being hackable

Not the reference implementation, but the major compilers and libc’s are not easily hackable.

• The standard library (or equivalent) has complete documentation

Yes, man pages.

So C meets 7/10, it passes!

go

• Most/all documentation is available offline (officially, something like zeal doesn’t count)

Yes, via godoc.

• Most/all documentation is available without a web browser

Yes, `godoc` is web-only but `go doc [QUERY]` is in the terminal!

• If it does require a web browser, it is viewable in a terminal browser like lynx

Absolutely! Works great!

• The documentation is well-organized and easily browsable

Yep, organized nicely and easy to find the function for what you want to do even if you don’t know what/where it is exactly.

• Bonus points if third party libraries can easily add their documentation to the offline documentation source

As a bonus new modules are automatically added to godoc as you download them!

• The language has a clear, consistent specification that anyone can read

Yep, it’s great!

• The language has a formal specification at all

Yep!

• If there is no specification, the reference implementation is easily readable and understandable

Very big, not really.

• Bonus points for the reference implementation being hackable

Ehhh, not really.

• The standard library (or equivalent) has complete documentation

Yep, via godoc.

So Go passes with 8/10, as a C-inspired language it makes sense that it’d be C’s equal, but IMO Go’s documentation is better than C’s so the extra point makes sense.

python

• Most/all documentation is available offline (officially, something like zeal doesn’t count)

Yes, but has to be manually downloaded from the python website.

• Most/all documentation is available without a web browser

Yes, but the non-web versions are raw html→XXX conversions so they’re pretty inferior. 0.5 points here.

• If it does require a web browser, it is viewable in a terminal browser like lynx

Yes, it’s /usable/ but not optimal.

• The documentation is well-organized and easily browsable

Yeah, I suppose so.

• Bonus points if third party libraries can easily add their documentation to the offline documentation source

No, not at all. There are third party things like sphinx but there’s not one source for docs, they’re spread all over.

• The language has a clear, consistent specification that anyone can read

Yep.

• The language has a formal specification at all

Yep.

• If there is no specification, the reference implementation is easily readable and understandable

Not really, if you don’t know cpython then you’re pretty SOL.

• Bonus points for the reference implementation being hackable

Nope.

• The standard library (or equivalent) has complete documentation

Yep, in the aforementioned documentation.

So python gets 6.5/10, better than I was expecting.

conclusions

I was going to go over more languages but I got lazy. I don’t even know what point I’m trying to make other than that documentation is important, but there is one major takeaway from this: rust is a shitty language with shitty designers and a shitty community. That’s for a variety of reasons, not just this documentation thing, this is a symptom, not a cause, of rust’s problems.

My post meant to emphasize good documentation turned into a rust sucks post, yay! I need to make a real rust sucks post sometime soon, it’s been coming out on fedi more than I’d like.