Diesel: Better Documentation

[theduke]

I think lack of documentation is a huge road block for Diesel adoption.

Each time I try to get started with Diesel, I have to struggle hard to not drop it and just use one of the raw database libraries.

The guide is VERY basic, and the source docs don't offer much either.

I would imagine I'm not the only one suffering from such frustration.

As a positive example that could be emulated, I think Rocket has managed a very decent, well structured guide that makes it easy to get started with and use.

[killercup]

Yep!

Any concrete ideas what the documentation needs to cover that is currently missing? We want to add more guides (there is one PR to add a guide on updates), and any indicator what is needed the most would be helpful. :)

[theduke]

@killercup
You have probably put more thought into it, but, off the top of my head, here is a raw structure for the documentation.

• Quickstart:
  A short single file (main.rs) example that shows how to: create a schema with table!, get a connection (don't bother with dotenv), run a raw SQL statement to create a table (not bothering with a migration), insert, query and delete rows.
  Concise, just get you something running quickly, and refer to best practices being mentioned in later chapters (dotenv, migrations, project structure, etc).
  Separate mirrored version for each backend would be nice.
• Concepts
  
  
  
  • Schema: explain schema and DSL, and different ways to get one (infer, table! macro)
  
  
  • Models: explain the traits (Queryable, Insertable, identifiable) and how they are used + how deriving works
  
  
  • CLI (short intro, important for migrations, more detailed docs below)
  
  
  • Migrations
  
  
  • Backends (postgres, mysql, sqlite)
  
  
  • Recommended Project Structure
  
  
• Queries: most important - Include lot's of examples
  
  
  
  • DSL:
    
    
    
    
    
    • basic insert/update/delete, arguments
    
    
    
    • querybuilder
    
    
    
    • Complex Queries (joins, ...)
    
    
    
    • Executing Raw SQL
    
    
    
  
  
  • With Models
  
  
  • Associations
  
  

• Backend
  Documentation for setup and custom features for each database

  • Postgres
  • MySQL
  • Sqlite
• Advanced
  
  
  
  • Custom Types (related traits, how to implement)
  
  
  • Handling Migrations (embed in binary, etc)
  
  
  • ...
  
  
• CLI: CLI features and available commands

[theduke]

I'd recommend not just writing more guides, but writing a structured documentation like above that can also be used as a sort of reference to quickly look up how to do certain things.

Especially with a ORM that's very valuable, imo.

I'm not in love with how https://github.com/azerupi/mdBook looks, but it's good enough for Rust, so using that might be an option, and certainly less work than building something custom.

[alanhdu]

To add my two cents:

The single biggest thing that'd make Diesel easier to learn is to add way more examples. Basic SELECT, INSERT, DELETE, and UPDATE queries are covered already, but for anything non-trivial it was much easier to look at Diesel's tests than at the API docs. Honestly, I think finding some SQL tutorial somewhere and documenting how to do every single query with Diesel would be a huge improvement.

In particular:

• How do you use GROUP BYs? I can do simple things, but eventually resorted to raw SQL because I couldn't figure out how to do a GROUP BY ___ HAVING filter.
• I still have no clue how to do a JOIN with Diesel
• I'm not sure there actually is a guide to dropping down to raw sql() -- I just kind of copy-pastad other code that seemed to work.
• How do transactions work? I kind of get the gist from reading the tests, but actual documentation would be great!
• On a smaller note, I wasted a lot of time trying to finding ne_any. - A table mapping operators to functions (or even just a a link to http://docs.diesel.rs/diesel/expression/expression_methods/global_expression_methods/trait.ExpressionMethods.html) would have saved me a lot of time.

[alanhdu]

Oh and also... I'm not sure how feasible this is, but I'd love a guide on how to read Diesel's compilation errors. They get pretty nasty, and sometimes I honestly have no clue how to use them to figure out what's wrong.

[theduke]

To suuport what @alanhdu said, i think the Queries section in my outline is by far the most important.

[DavidBM]

One think that I miss, is a list of all possible items. Like possible annotations for models in the struct. Sometimes, just a list of all the items helps as an index to see the possibilities.

Is not to make the information more easy to read, is to have a entry point to see all the information.

Now I'm searching if there is any annotation for telling diesel that ignore one field of the struct. I'm searching in the issues, in google, in the docs, but I don't find any place with all the possible functions, macros, annotations, etc of Diesel. In other frameworks I can read the full documentation in case of not finding the answer, here... there is no "all documentation".

As @alanhdu says in https://github.com/diesel-rs/diesel/issues/853#issuecomment-292817084 in the last point, a list of things that can be done.

[blanham]

Perhaps it might make sense to create a new repo specifically for the diesel.rs homepage? At the very least the existing guide could be expanded.

[sgrif]

The repo homepage is sgrif/diesel.rs-website

[killercup]

Just as a heads up to others, @hobofan said he'd like to start a query builder guide, and @notryanb want to document model derives/traits.

[notryanb]

Update - I'm currently working on updating the Associations docs for v1.0 and a separate guide for Joins.

[aliyazdani]

I'd love to see more docs too - especially for sqlite. This is my first try at Diesel with Sqlite3. Most of the examples I find are for PG and unfortunately we don't have that option atm. The examples on the repo for sqlite are extremely basic. I managed to get my inserts and updates working but a basic select query is generating a ton of compiler errors that are hard to understand. I can't imagine what a join requires.

I'd be happy to lend a hand if needed (even though I'm still a Rust noob at this point). Thanks!

[sgrif]

Once all open doc PRs today are merged, we will be able to add #![deny(missing_docs)] to the repo. #1407 (hopefully) addresses the "I don't know where to find things" issue (please comment on that PR with your feedback though). I've reviewed every single piece of documentation in the library over the past few weeks to make sure it's up to date (I likely missed a module somewhere, please open an issue if you find anything that is out of date or poorly documented). I'm hoping to publish ~10 more guides before the end of the year.

I realize not everything is documented as perfectly as it could be. If you have any concrete places where the documentation could be improved (even if it's just "I couldn't find/figure out X, here's where I looked") please open an issue.

However, I think we have sufficiently resolved the issue of "our docs generally suck" enough to close this.

[wangzhengqing]

i have readed the document. but i still dont know how to use "use schema::posts::dsl::*". diesel created these models or i have to write by myself? i really dont know how to do it.