Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update and enhance API docs' front page #988

Open
wprzytula opened this issue Apr 24, 2024 · 2 comments
Open

docs: Update and enhance API docs' front page #988

wprzytula opened this issue Apr 24, 2024 · 2 comments
Labels
documentation Improvements or additions to documentation
Milestone

Comments

@wprzytula
Copy link
Collaborator

wprzytula commented Apr 24, 2024

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:

  • explain that major part of the configuration is done using SessionBuilder, another one using ExecutionProfiles, 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.).
@wprzytula wprzytula added the documentation Improvements or additions to documentation label Apr 24, 2024
@wprzytula wprzytula added this to the 1.0.0 milestone Apr 24, 2024
@Lorak-mmk
Copy link
Collaborator

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

@DanielHe4rt
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants