Let's talk about ecosystem documentation

I personally enjoy writing good documentation. Libraries aren't complete without it IMO, and there are few things more satisfying than producing a complete library. A good API with good docs can read like a good story. :smile:

To a first approximation, I agree with the evaluation criteria. Specifically, the linked blog post provided some good context and I very much agree with the rationale there. To a second approximation, I'm not totally convinced that all sections need to be properly fleshed out. Specifically, smaller libraries probably don't need long form docs. A solid module level introduction with good API docs and examples is usually enough in my experience.

I'd like to echo some of others' thoughts on motivating documentation. In some ways, it's a social problem. What can we do to provide positive reinforcement for writing good documentation? Others have mentioned some good ideas. I really like the idea of showcasing well documented crates, although this does imply some form of manual curation. I would personally consider it important enough to be mentioned in any introductory guide to crates.io. Something like: "If you want others to use your code, then increase the likelihood of them doing so by teaching them how to use your code."

Also, I have personally come up with weird hacks to upload my docs to a web server somewhere. This saves me from having to do any kind of per-crate setup: all I have to do is add it to my "meta" Cargo.toml. But if this were done for me by Cargo/crates.io, then that'd be great.

I'd just like to say this I vehemently disagree that this is true. I've written a lot of Rust and I come across crates all the time that are just a pile of method signatures and traits and sub-module sprawl. I end up completely lost and uncertain how the author intends for me to use their code. In almost all cases, I end up having to read the source or the tests or find something that has that library as a dependency and use that as an example. Sometimes I can't find these things or they aren't enough, and in the end, I can't be sure that I understand how to use the library correctly. This is not a Rust specific thing either.

I think my point here is: experienced Rust programmers need documentation too. We shouldn't enable the "this crate is only for experts any way, so I don't need to write docs" line of thinking. :slight_smile:

OK, let me end on some positive notes:

  • I think the single biggest roadblock to writing good documentation is having easy to use tools for doing so. I think that rustdoc has solved this problem to a large extent right from the get-go. This is so not true in other ecosystems (to the extent that I've written my own documentation generators). There is tons of room for improvement of course, but I just want to echo that one of the major problems other ecosystems face is not present here. That's a really wonderful achievement.
  • crates.io and Cargo.toml puts documentation at the front of the picture by showing links to docs. This helps let everyone know that we care about docs and you should too.
  • Providing a way to run tests inside documentation is wonderful because it gives us a way to show examples that we can be confident are correct.

I wonder, do we have a guide anywhere on "how to write docs for Rust crates"? I can think of a few things to say on that subject... (Document your type variables gosh darn it!)

6 Likes

Well spoken as always.


Something else that could be done for crates is having topic landing pages of some form. Take algebra for example (I've never used any of them). There are 34 crates over 4 pages. It's pretty unlikely that I'll even look past page 2 for something. I'll just click the few most popular maybe, go on IRC to ask about what I'm looking for, then give up if I don't find what I'm looking for. Those could actually be a more general documentation resource which overviews the topic and available options. This would save individual crates from the hassle of having to document everything in the general sense even if they were willing.

Note: I don't know how well this would scale though. Consider this npm search for a sanity check. Maybe it would have one regular result with everything else specialized to some particular application I guess? I'm not really sure. It would at least guarantee the main result is the general one though.

Regarding documenting types and giving examples and such, there could be a doc lint for that. If you do generate docs and a function is missing an example or a type is exposed without being documented, there should/could be a warning.

I violently agree with both @Manishearth (my Rust mentor, btw.) and @burntsushi (whose crates are gold standard in documentation).

I wanted to add one point: discoverability and cross-crate linking. I find that the more connected (internally and externally) documentation is, the easier it is to find something, even if you don't know the name. The current docs emphasize use of the (very good btw.) search box instead.

Linking items from rustdoc still requires URLs, which (especially between crates) is quite cumbersome. I think we should have a way to link to arbitrary rust things (think crates, modules, structs, fns, consts, etc.) in an easy way that re-uses the information from Cargo.toml and crate imports.

Also we probably should have more ways to provide out-of-band documentation within crates. Have a way for rustdoc to include arbitrary markdown files in the documentation, perhaps?

2 Likes

I'm trying hard to write enough docs for Octavo that this would not only be fancy-new-crypto-lib but also I want it to be review of modern cryptography with long descriptions of algorithms. It should be almost book about cryptography, but I found some issues with current docs in progress:

  • no way to include math in docs. Only way is to use strange mix of unicode and ASCII-art to achieve simple and readable math. It would be much easier if there would be any way to use MathJax or similar to parse LaTeX math.
  • connected with above issue is that although Markdown is quite easy and simple (I like it a lot) I would much more see AsciiDoc as a documentation format (it isn't that much different from Markdown).
  • publishing docs should be easier as for now it requires complicated Git magic to publish it on GitHub pages (travis-cargo is just temporary fixup, not solution).
  • creating extra pages that do not describe code should be easier (i.e. all pages in doc/ folder should be automatically included in docs like all files in test/ are included in test suite).
  • there should be indicator in Crates.io that show how much code is documented, this would help with choosing well done package.
  • by default hide *-sys packages in Crates.io as most of users don't care (and should don't care) about them.

Other weird idea (which I'm not a fan) is star-rating packages. Like on App Store (i.e. "2/10 - It was great lib! Everybody should use it!")

2 Likes

For the docs of one crate, I fed math into something that typeset expressions in KaTeX online, then did something similar: copied the generated HTML (plus all the requisite CSS) straight into the Markdown.

It was impossible to maintain, and was a great way to hide typoes since the source was unreadable.

Really, the fundamental problem is that Markdown is rubbish at anything more complicated than trivially formatted text with links [1].

Aside: For the Iterator cheat sheet, I ended up resorting to a fairly hateful system of raw HTML + MathJax, loading the page in Firefox, waiting 60 seconds, opening the inspector, copying the "outer HTML" of the root html element, then pasting it into a "baked" version. Do not recommend.

I've got a little Python script that does all the requisite Gytnastics [2]; if I ported it to Rust and turned it into a cargo gh-pages command, would that constitute a "solution"?


[1]: Which, to be fair, was the point. I don't get why everyone and their dog keeps trying to use it for things which is was pretty specifically not designed for. sigh

[2]: "Git gymnastics"

1 Like

I really love this idea! Showing a percentage or a little progress bar next to each crate with the proportion of public items with at least some docs would be a great starting point.

There's a lot of great ideas here! I'd like to bring up 1 specific example:

From the serde page on crates.io you see two links, one for Documentation and another for Repository

The landing page for the serde rustdocs is a bit lackluster, with only a brief introductory paragraph, and nothing at all about how to use the library.

But if you click on the Repository link, you are brought to the github page with a most wonderful README, full of exactly the information a new user would want to see.

How can we consolidate this, and remove the need for a user two go to two different places for docs (one of which isn't even an obvious place for rich documentation, even though it is). Maybe by allowing rustdoc to pull in a README file?

1 Like

I'd be interested in an indicator for #![deny(missing_docs]. :slight_smile:

4 Likes

This is a good idea!

First Contact

I gave a five to regex:

It's got it all: instructions on how to use it, a link to crates.io, an overview of what exactly it provides, and a pointer to Regex, its main type.

The Black Triangle

I gave getopts a five here: http://doc.rust-lang.org/getopts/getopts/index.html#example

It's got a good, realistic example that shows off some things without being overly complex.

The Hairball

I gave bitflags a five here: http://doc.rust-lang.org/bitflags/bitflags/macro.bitflags!.html

This is also an example of what I mean about smaller crates. This crate shows off basic usage, but also more advanced usage, and comprehensively shows off what it can do. There's not a ton there, but there's not a ton to the crate either.

This page does make me reconsider our "show the source of macros inline" though....

The Reference

I gave env_logger a five here: env_logger - Rust

It's another example of "tiny crates are easier to document." While it's not perfect, it lays out everything that you can do.

README

I gave lazy_static a 5: lazy-static.rs/README.md at master · rust-lang-nursery/lazy-static.rs · GitHub

It gets you going, it has relevant information, and it isn't too long.

3 Likes

I absolutely agree and think this is important. Hence why I'm trying to get started on this early. :slight_smile: but good point, yes!

Yup, this is something we want, and we even have domain names, we just need to build it. "Just" :smile:

The problem is that it's very much tied to Rust's internals and build process, and without a "cargo install", makes it hard to use. It's one reason I got started on the cargo install work...

Absolutely, which is why having some way for pointing out markdown files to cargo or a tool on top of rustdoc like rustbook is important.

Yeah, this is something I wondered about too.

Oh yeah. It's very important to have good docs for experts too. I just mean that I think they're extra important for beginners.

https://doc.rust-lang.org/book/documentation.html

1 Like

We almost included mathjax, but didn't want to have the overhead for everyone. Where's that issue.... ah, here: https://github.com/rust-lang/rust/search?q=mathjax&type=Issues&utf8=✓ I guess my memory wasn't exactly right.

You can do this by passing flags to rustdoc, but that doesn't help with cargo right this moment.

I am not sure this is true. It depends on what you're doing.

Yes, this is a pain point with Serde I myself felt last week :slight_smile:

I'm using SVG in glium for things like this.

Example
The source

Do you think there should be a kind of rough documentation standard for Rust?

[quote="eminence, post:25, topic:2791"]
How can we consolidate this, and remove the need for a user two go to two different places for docs (one of which isn't even an obvious place for rich documentation, even though it is). Maybe by allowing rustdoc to pull in a README file?
[/quote]How about the other way around: Rustdoc generates a mardown README if asked to do so that is simply the module's documentation.

we have https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md though it could probably be publicized more. The Documentation chapter explains a bunch of it.

Well, actually, I was talking about something like a documentation style-guide in the form of a minimal template that should be recommended on crates.io and is mentioned in Cargo's getting started guide.

Projects should have a section dedicated to:

  • Overview of the entire crate, which consists of
  • General description of the crate, such as its scope and its domain
  • Demonstrative examples that clearly show a situation in which the crate is obviously useful, coupled with
  • Demonstrative solutions that show the crate does, in fact, solve the problems it says it does
  • Installation instructions, if there are any. While many crates are just a pull away, many others are not and require setup.
  • Assumes-Nothing Tutorial, which introduces the user to the library in a pedagogically effective way. Optionally this should include a simple example problem statement that is refined to be more and more complex as the tutorial progresses to necessitate introducing more features from the library.
  • Any more advanced subtopics as necessary, optionally following the same pattern as above.
  • A link to the complete API documentation.
  • Optional guide on contributing, external sources of documention (useful for library bindings), etc.

I admit that much of that is sort of obvious to some people, but remember that 1) programmers are not always technical writers, even though the field is requiring a greater amount of interdisciplinary skills and 2) people will do the right thing when given the smallest amount of push most of the time. With this in mind, if you remind people of this "obvious" structure frequently (i.e. whenever submitting a new crate), then they will end up writing it. Also, even if people are writing good and/or great documentation, if people write documentation in the same consistent way then documentation for projects will become predictable in content and structure, which is a tremendous boon for the user. Being able to say "I am going to go to the one source of documentation and find ____" is a great deal better than the situation eminence was referring to.

I am not a bureaucracy junkie. While people will write whatever amount of documentation at whatever level of detail that they want, having human interface guidelines floating around does not hurt anyone.

This is interesting. I was unaware of this lack of consensus over the purpose of the readme or it's being shoehorned into the one super document (though it's really no different from the crate summary being the one super document). Maybe this partially comes from github being the homepage of most crates.