[Input wanted] Diesel documentation improvements

[weiznich]

The diesel project is looking for feedback and additional input on their documentation for the upcoming 2.0 release. We have an ongoing PR here that touches a lot different items. I want to use this chance to reach out to potential users to get answers to the following questions:

• Is there something that is missing from the API documentation in your opinion?
• Did you remember searching something longer than expected in our documentation? If yes do you remember details?
• Can something else be improved on the existing documentation?
• Anything else you want to tell us about the API documentation.

Looking back to your answers here or in the linked PR.

[Heliozoa]

Some thoughts I had when using diesel before:

• I found the guides really useful. For a complex crate like diesel it really helps to have a high level overview in addition to API docs. I'd love to see one for queries eventually, even if it starts out barebones.
• I found it really surprising that Queryable relies on the order of the fields in the query and struct matching when first using the crate. There's a note about this in the trait's 1.4.x docs but it's been relocated to the derive docs in master. I'd actually like to see this emphasized more than in 1.4.x.
• I had some trouble finding the right method for fetching just one row and initially concluded that it doesn't exist and I should just use RunQueryDsl::load. In hindsight RunQueryDsl doesn't have many methods at all and I could've just took a look at them.

Looking forwards to 2.0!

[Roms1383]

I forgot some of the thoughts I had while using diesel but one which persists is that I remember struggling trying to build queries dynamically, at least in the beginning (it gets some time being used to the extensive diesel sets of traits, for a Rustling). I haven't gone through the latest documentation updates however I think this is one point that the docs should emphasize, as it turns out being the most common task a developer will want to do as soon as the project grows. I also remember there are some cases where trying to get diesel implementation "dynamic" was, to my own surprise, actually counter productive, in regards of the investment required vs benefits gotten: I think the docs should emphasize when it's worth the effort and when it's not, as much as possible.

[weiznich]

Thanks for the input.

@Heliozoa

I found the guides really useful. For a complex crate like diesel it really helps to have a high level overview in addition to API docs. I'd love to see one for queries eventually, even if it starts out barebones.

Adding a guide about queries is something I want to add. The problem there is that writing a good guide takes time, which is something that I do currently not have much That written any help there is welcome. This includes discussion about the potential content of such a guide.

@Heliozoa

I found it really surprising that Queryable relies on the order of the fields in the query and struct matching when first using the crate. There's a note about this in the trait's 1.4.x docs but it's been relocated to the derive docs in master. I'd actually like to see this emphasized more than in 1.4.x.

This was moved to the derive documentation because #[derive(Queryable)] relies on that order, not Queryable by itself. Manual implementations can choose a different strategy there.
Do you have any concrete suggestions on how this could be emphasized more?

@Roms1383

I haven't gone through the latest documentation updates however I think this is one point that the docs should emphasize, as it turns out being the most common task a developer will want to do as soon as the project grows. I also remember there are some cases where trying to get diesel implementation "dynamic" was, to my own surprise, actually counter productive, in regards of the investment required vs benefits gotten: I think the docs should emphasize when it's worth the effort and when it's not, as much as possible.

For me this sounds more like the topic of another guide as there is no real place in the API documentation to add this information. Or do you have some concrete suggestions here?

[Heliozoa]

@weiznich

Adding a guide about queries is something I want to add. The problem there is that writing a good guide takes time, which is something that I do currently not have much That written any help there is welcome. This includes discussion about the potential content of such a guide.

I'll keep it in mind, I should have time to put into a project that uses Diesel this year so hopefully I'll have more input on it than just that it would be nice to have.

@weiznich

This was moved to the derive documentation because #[derive(Queryable)] relies on that order, not Queryable by itself. Manual implementations can choose a different strategy there.
Do you have any concrete suggestions on how this could be emphasized more?

Yeah, I get that details specific to the derive are a bit awkward to have in the trait docs. Maybe the sentence that links to the derive docs ("This trait can be derived") could be rewritten to more strongly suggest that you should take a look at them if deriving the trait. A mention in an eventual query guide would help a lot in any case.

[Roms1383]

For me this sounds more like the topic of another guide as there is no real place in the API documentation to add this information. Or do you have some concrete suggestions here?

You're right, elaborating on diesel.rs guides indeed.
Common questions I remembered having:

• how to automate CRUD operations with diesel ? (e.g. diesel-crud crate, but some explanations about implementation process helps understanding how diesel works)
• is it better to use monomorphization or boxed traits when turning one's code generic ?
  when is worth the effort ? what are the potential tradeoffs ?

Out of scope, but I'm pretty sure everybody wonders at some point:

• mentioning about diesel in an async context (I'm thinking about diesel-transaction-handles crate)

I haven't been through the docs for over a month, so my apologies if some suggestions are actually already documented.

I also noticed on the chat people, myself included, often asking similar questions when starting with diesel, so probably some facts could to be emphasized too.