A Rust Documentation Ecosystem Review

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

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

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.

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.

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.