Documentation

[frnco]

I mostly rely on documentation, even man, --help and stuff. I'm also using Arch Linux for quite a few years now, and I really believe people should read the docs and learn how to do stuff instead of asking others and copy-pasting stuff. But for that the docs need to actually have information needed. I am going through the examples in the iced repo and I think they're amazing, but even then I'm still having quite a it of trouble, especially with types, which type is returned by this or that thing, etc. Plus I love the idea of isolating state and being as functional as possible, but even though I'm looking pretty hard for ways to split stuff into modules and how to isolate state and stuff, it's been an uphill battle to cross-reference the code in the examples, the little info on the docs, and the errors my compiler produces pretty much every time I write anything.

I took a look at the issues to check if and how many others had similar issues and it seems a considerable number of issues can be solved with better documentation, as opposed to bugs or features. Now, I'd love to help with that but I'm still learning Rust. Even so, I do have some suggestions on how to improve this mess.

1. First of all, I'd suggest creating a Label for Documentation stuff. A lot of stuff that is marked as Question on Unlabeled is stuff that should be answered by the documentation, so less and less people have to ask questions in the first place.
2. I'd suggest annotating argument types and returning types for as many methods/whatever as possible. It's probably worse for me since I'm more used to dynamically typed languages, but I've done my fair share of public static void stuff and I'm pretty sure there are a lot of people with a lot less experience with types. Couple rust type annotations being written after the function definitions with the nested <> from hell in type annotations, and the lack of type annotations or instructions on why they shouldn't be necessary in the first place makes it quite a bit harder to work with iced.
3. State. It's not very functional to actually have state anywhere other than the arguments and returns you're throwing around, so I'm still trying to make peace with that, but I feel there should be more info on how to actually store "state". Be it scrolling, buttons, sliders or whatever. From what I understand, everything is in the sruct named after the application, and those values are initialized by the new method in the impl Application for, but I learned this and pretty much everything else by reading through the examples and trying stuff out, when the docs could make it more obvious that Messages keep the functions that the GUI calls and functions that modify the GUI, state is in your app's struct etc.

I believe those should be fairly easy to do, and could already be a big help. Especially some explanations on the structure (And how this structure is translated on the example apps, more comments there would help a lot), and how to split logic if necessary (i.e., if I have too many screens and want to have a separate file just to build the views, how should I organize it? Or what if I wanna keep the state upon closing, so the user can continue from where they left off, how could I deal with that saving/loading?

This stuff probably seems trivial for people who are more experienced with Rust, but I think that's exactly why this stuff should be added to the Documentation: Because it's easy to add for people who are writing the documentation, and not writing it will most likely result in an increase of issues created which in turn will take a lot longer to deal with.

Beginners will still have trouble with mutable stuff and whatnot (At least I believe I will, for a while), but that's exactly the reason why I believe documentation and examples should have more details on types and stuff, because I shouldn't need to read through iced's code or a bunch of compiler errors to figure out what each type returns, and the maintainer shouldn't have to waste time explaining stuff for a small number of people in the issues as opposed to just adding that to the docs.

[rosenjcb]

I've been noticing some critical documentation needs too. In particular, the styling aspect of iced follows a lot of conventions from CSS, mobile styling, et cetera but there are some key differences that you won't really discover until you dig into the source or the docs.rs page. E.g. I believe that there's a thread where the flexbox concept was abandoned in favor of something more modern but none of the granular details are found outside that thread.

It might make sense to start defining what base widgets exist in iced and what styling properties are available each widget. E.g. I believe you can add padding to a Container but not to a Text. Also there's a rudimentary StyleSheet trait for each component that isn't explained very well. I'd be willing to write such documentation or even help develop the standard, but I probably need to hack at the project more or talk to the contributors a bit.

[13r0ck]

Already in the works https://github.com/iced-rs/iced-rs-docs, good docs just takes time. Please be patient.
If you are willing to help, please do!

[rosenjcb]

@13r0ck Sounds great. I can fork the project, make a .md page, and just write down what I've discovered so far. I'll make a PR so that we can talk back and forth about the topic and I'll probably learn a lot of things as well.