search

iced-rs / iced-rs.github.io

iced.rs website
https://iced.rs
MIT License
3 stars 4 forks source link

Tracking issue for guide-style docs. #2

Closed cldershem closed 2 years ago

cldershem commented 3 years ago

iced needs tutorial and guide style docs. Currently the project only has reference docs and code examples while relying too heavily on the elm explanation docs.

I think actix-web did their doc organization pretty well. I like that it's a lot of small, composable pieces that one can quickly find a feature and also see how things work together. At the time of the actix-web 1.0 doc rewrite, we tried to make every section it's own crate so that, at least in theory, the docs could be tested against new versions to show breakage. By having a bunch of smaller sections it also makes it easier for multiple people to work on and write different parts simultaneously. I also believe it would be good to make sections based around not only features, but the basic building blocks of an application (ie. 'how to display a list of things', 'make a basic login form', instead of a generic text_input section). I also am of the opinion to hesitate before just linking strait to the elm docs for questions. The elm docs might have inspired iced, but they tend to get a little heavy into dogma and not so much in practice. The docs also need to link to iced_native when required.

Topics

As far as technical stuff, I'm a fan of zola and plain text/markdown, but I'm open to whatever.

I will update this issue as I figure more out.

hecrj commented 3 years ago

Agree with using zola and plain text/markdown. @AlisCode started working on a Zola theme for the website in https://github.com/iced-rs/zola-theme around a year ago.

I also like the idea of focusing on practice rather than theory. Rust, while very opinionated, has a strong focus on pragmatism.

AlisCode commented 3 years ago

For what it's worth, I remember starting to write that theme, though I did not take enough time to actually get somewhere, and I got blocked by the issue on Iced branding that's been going on for quite some time now, and I'm unclear on what can be done at this point.

cldershem commented 3 years ago

@hecrj Agreed on the pragmatism, it's one of my biggest frustrations with the community as a whole. Instead of being passive aggressive, I'm being actively aggressive by writing better documentation! :smile: The link I mentioned in the docs has a lot of good info on how to structure different types of docs. I'm going to attempt to follow that as closely as possible.

As far as a theme, I'm not too worried about that. Zola is easy enough to swap that in whenever someone makes one. Right now, I'm focused on making sure I understand iced well enough to get started. I'm also a newcomer, which puts me in the perfect position to know what questions I've had, but I don't want to spread bad practices.

cldershem commented 3 years ago

Here is a working example of what I had in mind for the new docs. Obviously it doesn't look great, but it's quite functional. You can view the README.md in the source to get an idea of how you'd add and edit documentation. Someone that is better at theming/design/ui can make this look a lot better.

The main idea is that all of the code is real, working code that you can include snippets of in your docs. It's not setup to compile against new versions of iced yet, but it wouldn't be difficult to do. That would allow for us to test for when the docs need to be updated.

The demo/tour page is a bit clunky, but it will work for now to not lose any of the current showcase functionality.

Let me know if you've got any problems or have any questions. I wanted to finish at least one page of real documentation, but I just haven't had time yet.

hecrj commented 3 years ago

@cldershem This is so cool! The automatic embedding of code snippets is awesome!

It'd be cool to eventually be able to embed working Wasm versions of the examples in the docs too. We may be able to do that once https://github.com/hecrj/iced/pull/517 lands.

I think the styling needs some fine-tuning for sure (table of contents and spacing, mainly). Maybe we can just copy most of it from an existing project.

As you say, the demo page is fine for now to keep the current showcase functionality.

cldershem commented 3 years ago

I agree on the styling. I'm no designer, I just got it "good enough" to get us started. I didn't want to put a ton of effort into it if the functionality wasn't there. If you like the idea, we should move the project to the https://github.com/iced-rs/ namespace to get more eyes (and hands) on it. I think we can probably toss it under "dev.iced.rs" or "docs.iced.rs" for right now and then when we have some actual content, swap it over to the main url.

I'm open to any suggestions, I just wanted to get things rolling.

hecrj commented 3 years ago

@cldershem I have invited you as a member of the organization. I believe you should be able to create or transfer a repository. Is that correct? Anything else you need me to do?

I believe tossing it under a subdomain of iced.rs may conflict with the current website and GitHub Pages.

cldershem commented 3 years ago

@hecrj Thank you. I was able to transfer ownership to the iced-rs org. The new repo is https://github.com/iced-rs/iced-rs-docs . It will be a few days before I have any time to really dive in, but in theory it should be open for contributions.

hecrj commented 2 years ago

This will be tackled with the new book effort: https://github.com/iced-rs/book