Standardized documentation

[David-OConnor]

Summary

All Gloo modules should have narrative documentation, perhaps as part of a centralized guide.

Motivation

It's common in the Rust community to rely on API docs, and narrow-scoped examples. These are important, but not sufficient.

Detailed Explanation

With some exceptions, Rust libs, including most WASM frameworks, tend to be documented through examples and API docs. While these are important, having a detailed, narrative guide is important too. For example, the Rust book. I think all Gloo components should have a maintained guide of this style. Could use the Rust Book template. Example: Vulkano has a very extensive API, a guide demonstrating some things, and a few examples, but is missing large chunks of info, like how to use it for 3d items, or multiple objects. Example: Yew is a popular stdweb-based framework, but has no narrative guide outside a brief readme, which until recently, was misaligned with the released API. Example: Rocket is a backend framework with a detailed guide.

Related: In addition to feature-specific examples, and long/complex ones, I think short ones that demonstrate API coverage, and using various features together are useful... and missing in many Rust crates.

Drawbacks, Rationale, and Alternatives

It requires more upfront effort, and maintenance work when APIs change.

Doing this would make Gloo more appealing to people who are experienced with frontend dev, but not Rust.

[fitzgen]

Thanks for bringing this up!

It isn't 100% clear to me whether you are suggesting

1. a guide to Gloo, the umbrella project, with sections for each of its crates plus whatever else fits, or
2. each crate within the toolkit has its own guide.

I am super down with (1) but I fear that (2) may be a bit all over the place, and make finding the right docs difficult.

Assuming we are on the same page with (1), would you be interested in submitting a PR to add a skeleton of an mdbook guide and a checkbox to CONTRIBUTING.md saying that each gloo crate should have a section(s) within the guide?

Aside: one pattern that has worked well for wasm-bindgen in terms of balancing maintainance costs and having lots of examples in a guide book is to use mdbook's file inclusion features so that we can test example code and make sure it compiles.

[David-OConnor]

I'm referring to 1. Will do a PR.

[ranile]

I think the new website would be a great place for this documentation. I switched away from mdbook because there wouldn't have been enough content to call it a "book" and a website gave us more flexibly. I would love have the documentation worked up on the website as it's quite lacking at the moment.

[anshulrgoyal]

@hamza1311 I am interested in adding documentation.

[anshulrgoyal]

What is your vision for documentation on the website?

[ranile]

What is your vision for documentation on the website?

Honestly, none. I'd like to just remove the documentation section from website and use docs.rs. The only documentation related thing on the website is getting started guide, which can be moved to module level docs for gloo. The homepage and blog can be left as-is (or replaced with something lightweight like Astro).

Looking through what's missing and adding documentation as rustdoc is a good place to start