Hacker News

A Rust Documentation Ecosystem Review

• 15 Comments
• SNAFU author here, thanks for including my crate! I’ll try to give your review a thorough read through later and incorporate feedback that makes sense.
  I do have https://diataxis.fr/ and related stuff open in another tab and keep meaning to figure out how to best apply it for SNAFU.
  Out of curiosity, do you recall if you also read the top-level docs[1]? That’s intended to be the main introduction, I actually don’t expect most people to read the user’s guide, unfortunately.
  [1]: https://docs.rs/snafu/latest/snafu/index.html

  By shepmaster 5 months ago

• To be clear, this is not my review. I just found it very interesting and relevant to my own work.

  By hyperbrainer 5 months ago

• I see you every time I open Stack Overflow :D

  By LtdJorge 5 months ago

• This is a nice analysis of Rust documentation, but I find the continued emphasis on content types disappointing. I think docs should shift from what to write to what are the needs of users of the docs are. Then you can think of content types. If you don't, you just end up checking boxed just cause.
  https://news.ycombinator.com/item?id=42645075

  By theletterf 5 months ago

• Yeah, that’s a generous sentiment until you are trying to pull docs for a particular version of VAFileman from a .zoo archive . . .

  By adolph 5 months ago

• As a crate author a thing I don’t like is that rustdocs are not easily sharable even though the same code might be used in a function, module and readme doc.
  I took a stab at a JINJA based rustdoc templating solution: https://docs.rs/drydoc/latest/drydoc/. It’s not “done” but I think the idea holds promise. Anything else like this that you’ve seen? My other option is to use include_str macro.

  By schneems 5 months ago

• Thanks for sharing and good luck on your project. I think better docs is a worthwhile idea overall and although the implementation details may vary, a template solution could appeal to some people.
  Separately, I find it disheartening that people come into this thread with some bone to pick against Rust and just downvote everything they see without adding anything to the conversation. Part of me feels that a downvote should require a reply for this reason.

  By airstrike 5 months ago

• Thanks! I’m less soliciting for people to use this specific solution and almost sharing aloud hoping someone will say “duh use crate X”
  Thanks for the concern over votes. I think your comment turned the tides, I’m at +1 now.
  Overall Rust has the best doc eco system of any lang I’ve used. I wish more communities stole from rust. The most useful part of any doc is an example and rustdoc makes it really easy to write one and keep it from doc-rotting. My particular pain is for an author who aims to go above and beyond.
  Specifically I was thinking of the winnow tutorial when writing this crate. The return type example is straight from what I would like to be able to toggle on/off in their docs.
  I also have a more mature library for easing maintenance burdens for tutorial writing but it’s not rust https://github.com/zombocom/rundoc

  By schneems 5 months ago

• There's no downvote button for me, I had no idea HN had downvotes

  By flysand7 5 months ago

• FWIW I’ve got one. You need over 1k karma I think (or maybe it is based on some other metric).
  A post with more downvotes than upvotes will show up as grey for me too.

  By schneems 5 months ago

• The grey part is for everyone. Flagged posts show an even lighter grey, IIRC.

  By LtdJorge 5 months ago

• Great article. I deeply appreciate the work that went into it.
  I struggle with navigating most crates on docs.rs. It just doesn't have the things I want it to have, it's hard to quickly jump around definitions... 9/10 times I end up just cloning the repo and browsing through the code on vscode. I wish docs.rs was more like that experience but with nicely rendered docs to go along them.
  Also, as the resident diehard iced fan, I think the section on that library is pretty fair and I appreciate that. There's definitely room for improving existing docs by fleshing out some of the descriptions in modules and functions.
  Having said that, I do think the focus on `iced::application` and `Element` misses the forest for the trees a little bit, because those are some of the most generic parts of an iced application—`iced` is more about the plumbing between things than it is about those things themselves, if that makes sense. In other words, it's not super useful to talk about what `Element` is. It's just a generic widget. How it makes widgets generic is less relevant to the user, and certainly for beginners. It's better to talk about how it is used.
  The same goes for `iced::application` and its signature. It's honestly a ridiculously elegant design that hides away all the complexity needed to make this possible:

      pub fn main() -> iced::Result {
          iced::application(MyApp::default, MyApp::update, MyApp::view).run()
      }
  

  If that isn't the cleanest way to initialize an application, I don't know what is.[1]
  Again, it's better to talk about how those things are used than it is to talk about their specific implementation. And to that end, the docs include a "pocket guide" at the very index of the crate, which covers how those concepts fit together. The author addresses this in this paragraph, but I feel it also doesn't give it enough credit:
  > The rest of the crate root’s docs consists of snippets for each concept of the crate and how to start using them. They aren’t an exhaustive explanation of these concepts, but they’re a great venue for discovering what iced has to offer here in terms of API. And wow there’s a lot of concepts here.
  If you're starting with the library, I encourage you to go through the pocket guide and the examples to learn more. Alt-tabbing between the two should give you lots of opportunity to understand the many concepts and how they fit together.
  [1] The arguments are totally generic, so `MyApp::default` could be `MyApp::new` if you wanted or any other function that returns some instance of `MyApp` -- and which can _also_ return `(MyApp, Task)` -- i.e. your app and some task to run at initializing. That flexibility makes for very ergonomic code, and you don't have to worry about how it achieves that. Also note `Application` has uses the builder pattern, so you could just call `.title(App::title)` on it to set the title... and the argument there is, as you might have guessed, generic again. You could call `.title("My title")` and it would also work. That's beautifully designed.

  By airstrike 5 months ago

• [dead]

  By curtisszmania 5 months ago

• I have a habit of reading Conclusions of lengthy articles before I read the article itself to decide whether it's worth a read or not.
  This article had by far the most useless conclusion section.

  By xnickb 5 months ago

• > Please don't post shallow dismissals, especially of other people's work. A good critical comment teaches us something.
  https://news.ycombinator.com/newsguidelines.html

  By airstrike 5 months ago