[HN Gopher] A Rust Documentation Ecosystem Review
___________________________________________________________________
A Rust Documentation Ecosystem Review
Author : hyperbrainer
Score : 86 points
Date : 2025-05-11 12:08 UTC (10 hours ago)
(HTM) web link (www.harudagondi.space)
(TXT) w3m dump (www.harudagondi.space)
| theletterf wrote:
| 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
| adolph wrote:
| Yeah, that's a generous sentiment until you are trying to pull
| docs for a particular version of VAFileman from a .zoo archive
| . . .
| shepmaster wrote:
| 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
| LtdJorge wrote:
| I see you every time I open Stack Overflow :D
| hyperbrainer wrote:
| To be clear, this is not my review. I just found it very
| interesting and relevant to my own work.
| airstrike wrote:
| 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.
| schneems wrote:
| 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.
| airstrike wrote:
| 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.
| flysand7 wrote:
| There's no downvote button for me, I had no idea HN had
| downvotes
| schneems wrote:
| 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.
| schneems wrote:
| 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
| xnickb wrote:
| 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.
| airstrike wrote:
| _> 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
___________________________________________________________________
(page generated 2025-05-11 23:01 UTC)