Let's talk about ecosystem documentation

maybe there could also be some curatable 'auto-discovery' of interesting content (aka links) on cargo pages. AKA links to questions on stack overflow tagged/about the crate at hand, or discussion/descriptions/etc on forums/redit/etc and blog posts and such things?

People expect to find examples in both places. I want to see examples when I check out the repo of a crate, but I don't want to have to have two tabs open for each crate I'm using. A problem is also that you don't want to have examples in three different places, the ./examples folder the readme and the doc. My suggestion:

  1. no examples in the readme, point straight to the docs from there
  2. don't make the dev replicate the examples inside doc comments, this feature is neat, but my little crate e.g. is 50% docs, 50% of which is code again. I want an include(example/foobar.rs) feature for my doc :smiley:

Don't know but https://stackedit.io scroll to math yeah it uses MathJax.

I personally can't ever get on board with this. If your project's landing page is the github URL (which is pretty common), then I like to put a small example demonstrating functionality right near the top of the README.

Usually I pick the example out of the docs so that the examples aren't really split. But this approach is hard to maintain since it's easy for the examples in the README to get out of date. But that first concrete example to show others what the crate does is worth it. Something to run rustdoc on the README would be useful.

I admit, I wouldn't either, the problem is, there are currently 3 different places I want to find examples, and all of them have to be kept up to date. However it should be perfectly possible to read all markdown files that contain a ```rust ` code block and validate them the same way as the examples in comments.

What if the generic landing site for crates was some different type of page? For example:

Is there any reason the github page should be the main landing page? If you visit the repository, is it safe to assume you either want to browse the repository or deal with bugs/issues or build the code? Is there any need for more than really brief examples there? Perhaps the readme should be mostly install info and push most everything aside from a brief description to an external site. Actually, this is exactly what servo does and when I look at the github site, it's usually what I'm looking for.

This is somewhat rhetorical as I'm unsure if it would be a net gain if crates globally move to something like this by default. It seems like it would certainly help bigger crates. It also seems perfectly reasonable at least for an experiment.

2 Likes

A few ideas:

  • Add a way of publishing docs easily through gh-pages (via a cargo subcommand, for example)
  • Add a quick way of opening the docs in $BROWSER, for the lazy.
  • Add a CLI for browsing the docs (this would be nice, as many uses a terminal for programming).
  • Reward 'best documented crates'.
  • Add a list for crates that 'needs documentation'. This will make contributors able to find crates that needs documentation.
  • Make the search functionality better.

Not sure if this is exactly what you meant, but cargo doc --open does this, and it includes the docs of all dependencies.

6 Likes

https://blog.wearewizards.io/trying-rust-for-web-services is a blog post I found today.

Having spent some time trying to implement a parser with nom I must say reading tests, commit messages and raw source (macros can be really hard to figure out from source) is really the only way to figure out how to use the crate. There is a halfway decent readme but it leaves out a lot of crucial details.

That was my experience with a lot of crates as well.

I disagree. Markdown with the pandoc extensions has almost all the features I want, including math and tables. It can almost replace LaTeX for my use cases.

(Protected whitespaces are the biggest thing I'm missing ATM.)

(Emphasis mine)

I rest my case.

Markdown is an ad-hoc, inconsistent mess of a markup language, lacking just about every useful feature you want for good technical documentation. For all its faults, at least reStructuredText has well-defined extension mechanisms to fill in gaps where they existed, but even then was much better right off the bat.

Trying to use Markdown for this just leads you down a path of numerous, mutually incompatible, poorly defined and documented collections of random bits of functionality.

Or, to summarise my view another way: you can put lipstick on a pig and whack it in a dress, but it's still a pig. Tasty, sure, but frankly useless at interesting conversation and dancing.

Markdown is simple and easy to write. That's personally my most important feature for writing most technical documentation.

2 Likes

Right; that's what it was designed for. It's also about the only thing it has going for it.

Although that depends somewhat on how you define "simple": nesting inline formatting is rather hit-and-miss depending on which exact implementation you're using...

1 Like

The main reason I don't write more docs is because each change to an example, or wording change, or part re-considered, means another 2-3 minute build followed by 2-3 mins of example tests to learn if I got the spacing right on that 23rd example.

I understand that incremental compilation will eventually fix this, but that is the pain point at the moment.

Edit: and I should say, I think writing docs is pretty fun. I like that Rust actually has some structure to the docs, so it is clearer when I've said enough. I like the style guidelines on doc writing for this reason too. More guidelines would be great (less "oh geez, what should I even say" angst).

2 Likes

What about adding a small amount of gamification to doc generation -- have cargo doc report the number of items that have documentation. The idea is that people will feel a compulsion to get that number to 100% :smiley:

1 Like

I disagree. We can pick any Markdown dialect we want for Rust. There is no need for standardization. The pandoc extensions are neither mutually incompatible, poorly defined or poorly documented.

This would help me a lot. Mostly I look at a big pile of code that may need various documentation, and get overwhelmed. Something that points out missing documentation, or missing examples, or things like this would help motivate me to just pick a thing and run with it.

I'd love it if there were as many people chatting about how to improve documentation as there are people chatting about how to screw around with unsized arrays and string parsing. I get why they aren't doing that, but ...

For example, I'd love to get input on documentation, not just "did I write this well" but how do you work around issues like this:

http://www.frankmcsherry.org/differential-dataflow/differential_dataflow/operators/join/trait.JoinBy.html

which I think of as a bug, either in my exposed APIs or in how rustdoc thinks about presenting information. I can obviously write walls of text, but if there is experience with how to write well-understood interfaces without compromising on performance (zero-overhead documentation?), I'd love to know.

Is there an IRC channel for documentation?

2 Likes

I find that using where clauses help... but I doubt there's any way to "fix" something that complicated.

One thing I ended up doing in one library was creating high-level traits that just inherited from others to use as bounds to try and keep the noise to a minimum. That rather depends on being able to even define a coherent name for each unique set of bounds...