Elsewhere

A broad vision for the Rust docs stack

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.

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.)

As I observed, hunt hard enough and you’ll find http://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.

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.

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.

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.)

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:

good explanation at the top of the concepts and functionality;

genuine usage example—as in, bits of code that you can copy and verify to be doing what you want;

directing you to other good third party sources—even going so far as to say things like “this is a common use case, but it’s not in the standard library; here’s the technique most people are using” (Java, by comparison, is fairly leery of third‐party links);

oh yes, actually documenting the API as well (of course).

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

subprocess uses sound categorisation of things rather than alphabetical order or mere order in source. It also gives good examples, comparisons with what other people may be used to, security considerations, &c.

itertools uses tables to concisely demonstrate the information that most people will come for, before then proceeding to more traditional documentation, followed at the end by a large number of recipes. (Don’t constrain yourself to text! Something that would be useful in places in the Python docs is images. Yes, you can use images in these sorts of documentation; for comparison, here is one I prepared a few years ago, when using Sphinx in the PortableApps.com Launcher documentation; a flowchart augments the textual description of the same thing.

collections explains the purposes, gives usage examples, gives alternative data structures and implementations, provides links for implementations in other languages or for old versions of Python, explains briefly where it’s good or bad to use this, and so on and so forth.

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

Comments? Questions? Corrections? If you want to contact me about anything in this post, write to me at @__chrismorgan or email me.