Open wprzytula opened 4 months ago
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.
The front page of crate API docs currently:
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:
Two particular ideas from me:
SessionBuilder
, another one usingExecutionProfile
s, and some is done on statements directly;