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