A broad vision for the Rust docs stack

A presentation that I made to the San Fransisco Bay Area Rust meetup about the implementation side of Rust docs, and what I think should be used.

Yesterday (Tuesday evening in America, Wednesday afternoon in Australia) I gave a presentation to the San Fransisco Bay Area Rust meetup on the topic of the Rust documentation; Steve Klabnik, who spoke before me, dealt mostly with the contents of the documentation and I dealt much more with the tech stack which I thought would best achieve this goal (we agreed pretty well on the broad goals of the documentation).

I give especial thanks to Erick Tryzelaar for going to the trouble of arranging for this presentation to occur and for ironing out all the issues that arose in SF.

The slides

A video recording of the presentation is available on Air Mozilla; my talk begins at about 34:30 and continues until 55:00. The slides below are sufficient to get the significant majority of the important stuff from the presentation if you prefer.

View the slides here (SVG; you’ll need a “modern” browser to view them, or you could ask me to make a PDF of them for you)

The slides. Click, tap, arrow keys—​whatever you like.

These slides are best viewed in Firefox. (I just tried Chromium and it renders the SVG incorrectly in a number of places—​collapsing multiple sequential spaces into one in text, selecting the wrong font weight if you have the Ubuntu font installed locally, getting manual character offsets on the wrong characters in one of the slides… not good.)

If you’re interested in the tech that went into the slides themselves, I’ve written an article on that, too.

Now onto some of the other things I wanted to add more about in the languages section.

The Java documentation

Try to find the official Java documentation. Some places you might start:

As I observed, hunt hard enough and you’ll find https://docs.oracle.com/javase/. It doesn’t try particularly hard to head you in the right direction, but if you’re persistent you’ll find there are three main things it’s got.

  1. The root of the docs: https://docs.oracle.com/javase/7/docs/index.html

    OK, so… now where do I go? Oh! The table cells are clickable. How about we try Input/Output? Now what do we have?

    • A few links to things in different places—​the tutorials, for the odd topic a tech guide (often about actually implementing the feature itself rather than using it)
    • API documentation links
    • If you’re lucky, an example or two
    • And a bit of changelog

    And this is all of the Java Platform Standard Edition 7 Documentation.

  2. The official tutorials: https://docs.oracle.com/javase/tutorial/

    They’re decent for learning something, but frankly, I don’t have time to learn that thing. I already know Java, right? I just want to find out how to do this one particular thing. The tutorials also make dubious reference material, because they’re not geared to minimal examples; rather they’re designed for linear progression; the right one can also be difficult to find, assuming it even exists.

    They’re simply not designed for discovery. Everyone already knows Java or they’re learning it at University (also known as “college” or “school”) from other sources, and so won’t need them.

  3. The API documentation: https://docs.oracle.com/javase/7/docs/api/index.html

    This is the heavy hitter of the lot, and the heavy hitter in more ways than one.

    This is somehow the panacea for everything; you want to know what something can do? Here! Here’s what it can do!

    Now read this forty page document which explains what each method does and gain enlightenment.

I come away not particularly impressed. Yes, the Java community can produce fairly good API documentation as they go, but it’s not designed for learning, which is a problem.

An example

I’ll draw this all together with an example; in this past semester for a Computer Graphics unit (“course” for Americans) I was doing some OpenGL stuff in Java and I wanted a spinner (you know, the number entry field with arrows) for the window chrome; I wanted to find something in the official docs about them.

I found a tutorial about them, but I really had no time to learn it that way. I had my project set up the way it was set up and setting up a new project for that stuff and going through it in a linear fashion simply couldn’t cut it—​that would, all up, have taken hours.

Well, how about the JSpinner API documentation?

… that was even worse.

That’s why I conclude that pragmatism is what the Java docs are lacking.

(P.S. Remember that javadoc was once a pretty radical thing; Java has played a significant part in improving documentation standards, and the existence of javadoc means that Java projects do tend to have at least basic documentation. It’s really isn’t all bad.)

And as for that quote I used on pragmatism, here’s the source:

What sold me on Rust is how insanely practical it is…

/u/Jurily on Reddit

The Python docs

Start at https://python.org/. Look in the navigation. Ah! There’s “documentation”.

https://python.org/doc/. That’s a nice and easy‐to‐read thing but pretty much everything you could want is there and clear.

Let’s try the Python 3 documentation. https://docs.python.org/3/. Again, everything is nice and clear.

Do I want to look at the standard library reference? https://docs.python.org/3/library/index.html

This is no auto‐generated javadoc; this is curated. Look through it all; I don’t mind what you look at there because I know it’s all pretty good.

There’s a general pattern of things that I want to point out:

A few interesting examples (but don’t just look at these ones!):

A couple of other important things it shows are the module index (we can make whatever indexes we desire) and search.