scylla-rust-driver
scylla-rust-driver copied to clipboard
docs: Update and enhance API docs' front page
Motivation
When someone wants to start using the driver in their project, probably the first source of their knowledge is the API docs (https://docs.rs/scylla/latest/scylla/). At least this is what I do with new crates I want to use. There should be a sensibly designed top-down docs structure, so that a new user can quickly get a grasp of how to use the driver and where to look for further details.
Suggested work
Working together with people from outside the drivers' team (e.g. developer advocates - @DanielHe4rt), understand what are the main points of interests and/or confusion for the newcomers to the driver, and explain them clearly in the front page, without too many details. Create a tree-like structure with pointers to more specific documentation - these may be pointers to:
- the crate API docs (docs.rs),
- the driver's book (i.e. Scylla general Sphinx-generated documentation)
Two particular ideas from me:
- explain that major part of the configuration is done using
SessionBuilder
, another one usingExecutionProfile
s, and some is done on statements directly; - focus on mentioning the notable differences between the Rust driver and the other drivers, e.g. lack of composable load balancing policies (no RoundRobin etc.).
Related: Rust's de-facto standard tool for documentation book is mdBook. Our docs build both with Scylla's Sphinx and with mdBook but we publish only Sphinx version: https://rust-driver.docs.scylladb.com/stable/ I think mdBook version should also be published somewhere because this is what Rust users are accustomed to. Also it's style is much more readable imo
After a quick chat with @wprzytula about the docs, we agreed to use PR's like #980 to improve small things inside the Rust-Sphinx docs and also improve the crate docs with examples.