This was sorta discussed on internals but no consensus was reached. I thought the idea was okay but I wasn’t going to implement it so I was trying to give solid ideas of what it could look like.
What stumps me is how and if the built in doc systems could handle documenting something like iron which would be really complicated. Compare with say express whose docs really aren’t that good but still leaps and bounds better than iron’s.
Maybe if the docs generated a landing page like that express site with headers at the top dedicated to separating complicated topics into categories (such as lib docs, introductions, and further topics). Even if each category could each host sections like the rust book, would it be cohesive while still discussing things separately?
Most of your post basically seemed to suggest a lot of the documentation problems could (slowly) be fixed if someone documentation minded just started submitting documentation PR’s to every popular crate in existence. Aside from that, you stated rustdoc needs improvement but is do you have anything particularly in mind? They’re two very different problems.
Well, I wanted to see what others thought about things, but yes. There’s a number of smaller stuff, like the weird sizes of headings, but also the lack of long-form doc tooling for external stuff, which is sort of what you’re bringing up at the start of your post.
Okay cool. I’ve gotten the impression that some of the rustdoc issues are partially because a good way forward isn’t visible so progress isn’t readily being made.
So that’s why those NPM pages are so full. I go to one of those pages and all I want to find is the link to the docs or to the repository and I can hardly find either. I greatly prefer crates because it’s easy to find things and it’s really simple.
One idea would be to have a section for “Friends” or “Similar” which would list how they are different from a different library. Using Serde as an example:
- rustc-serialize is a similar but older framework which we have now superseded. We have these 3 features which make serde so much better: a, b, c
- capn is different and targets a, b, and c which are outside of our scope
Also, having a line-graph (is that what these are called?) which detailed where each crate stood in the ecosystem would be useful. You’d look at a child crate and realize it’s actually just a piece of a large piece. Labelling things according to categories would be really important here I should think.
- serde_macros / serialization -|- serde - | \ | - serde_json | |- rustc-serialize | | - capnp-rpc | / |- capnp - | \ | - capnpc | | - dbus-serialize | - rmp-serialize
These two ideas are for crates in case it wasn’t clear.
That quick little visualization would be immensely helpful, I think. I’m just starting to dive into rust myself, and I find that one of the things that is painful is, like any new(ish) language, you almost don’t know what you don’t know. There’s been many times starting out where I just didn’t know that I had different, possibly better options available to me.
Some kind of tree like this would be an excellent way to explore what’s out there.
Good initiative. This is one of the most important things we can do to improve the Rust experience.
I totally agree with this, but what about the opposite-- would you be willing to praise some particular crates or authors, maybe one from each type of documentation that earned a 5?
Basically, in your opinion, how are the crates that provide good documentation doing it? Could we look at those to see how we might encourage those behaviors in other crates? (ex: make them feel like the default, make them easy)
Some thoughts, in no particular order:
Centralized documentation hosting, ala CPAN or ReadTheDocs. It’s not horrible to setup your own documentation builds with GH pages or RustCI, but it requires some effort. And you have to repeat the process for every crate you make
Ideally, this would be tied into your Crates.io account. So you could just do
cargo doc publishand it is autopublished
I hadn’t heard about Rustbook until now. Perhaps publicize this more, or integrate it with cargo?
Rustdocs are not the right place for substantial examples and long-form tutorials (imo). Regular reference docblocks already eat up enough space in the code. When you provide an example-per-method, you often have a huge block of comments and a tiny public-facing method (e.g an example from my own code)
Writing markdown inside of a comment is a pain, and rustdoc finds interesting and surprising ways to explode. I’ve been bitten by stray spaces before a ``` nuking the entire comment, as an example
Asciidoc would be a lovely alternative/addition to markdown, giving more expressiveness and styling while still being (relatively) easily tooled
Evil option: Don’t let someone publish to crates.io unless they have documentation More realistically, provide some kind of social incentive to publish docs (rotating “spotlight” on crates.io front page for documented project, etc).
As to actually getting people to write documentation…I’m not sure. It’s the eternal boogyman of software: no one likes to write documentation. Reference docs are generally good for Rust because of the rustdoc integration (which is great!), but “how-to” and “beginner” documentation is sorely lacking. Perhaps by making it simpler to add documentation (via crates.io hosting) would lower the barrier to entry and more people will document?
Just as a note, this sounded like a big list of complaints…but I think Rust has a relatively healthy documentation ecosystem all things considered. And it has folks like you that are invested in making sure 3rd party libraries are documented, which is outstanding.
The fact that rustdoc is integrated means most libraries at least have reference docs…which is honestly more than many libraries in the wild. It’s partially offset by the fact Rust is more complicated to get started with, but I wouldn’t despair too heavily =)
Completely agree with @Manishearth’s suggestion for built-in publishing support. Having a hosted version of your crate’s docs automatically hosted and linked to from its
crates.io page would reduce a lot of friction. It would also provide a single authoritative source for all crates. It may also provide encouragement for authors who, after seeing their hosted documentation, realize that they’ve missed important pieces.
Two things I really love about
rustdoc are the built-in Markdown support and documentation tests. That the latter doubles as an example block for the associated method or function makes it even more enticing. I think we could extend this tooling to provide better support for the “first contact” and “black triangle” tasks by setting conventions about where this documentation should live. Building a landing page using
GETTING_STARTED.md files at the root of the project (and auto-generating these as part of
cargo new) would provide more complete coverage for these differing types of documentation.
The “hairball” section seems a little bit trickier, but we could leverage module-level docs to provide higher-level topic coverage and define a manifest that would enable an ordered TOC linking to said module docs. This certainly feels targeted to a much smaller demographic, but it would be really handy for larger, more heavily-used libraries and frameworks!
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.
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.
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
rustdochas 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.
Cargo.tomlputs 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!)
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 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?
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-cargois 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
*-syspackages 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!”)
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 .
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
htmlelement, then pasting it into a “baked” version. Do not recommend.
I’ve got a little Python script that does all the requisite Gytnastics ; if I ported it to Rust and turned it into a
cargo gh-pages command, would that constitute a “solution”?
: 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
: “Git gymnastics”
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:
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?
I’d be interested in an indicator for #![deny(missing_docs].
This is a good idea!
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
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.
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....
env_logger a five here: http://rust-lang.github.io/log/env_logger/
It's another example of "tiny crates are easier to document." While it's not perfect, it lays out everything that you can do.
I gave lazy_static a 5: https://github.com/Kimundi/lazy-static.rs/blob/master/README.md
It gets you going, it has relevant information, and it isn't too long.
I absolutely agree and think this is important. Hence why I’m trying to get started on this early. but good point, yes!
Yup, this is something we want, and we even have domain names, we just need to build it. “Just”
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.