Replies: 1 comment 4 replies
-
|
To repeat again what I already have written before: I do own you nor anybody else nothing. Please stop writing these posts, they are not helpful. It's generally really bad style to accuse maintainers of not doing their work and requesting them to do a certain thing. If you really need to have something done consider funding the feature/documentation/… you want to have. Otherwise I do not have any obligation to do anything for you. (And given you attitude I won't do anything for you). That written: We are aware that more documentation would be great to have (as for ~any other project out there), but in the end someone needs to write that documentation. Given that other people request more features or fixing certain bugs or something else there is just not enough time to work on everything at the same time. Also I do have my own use cases, that I prioritize for obvious reasons. The hard truth there is documentation does not pay me anything, while adding/polishing new features for products I develop does pay me something. In the end it boils down to: If you want to have better documentation (or anything else) the best way to make sure that this happens is to start contributing. Otherwise you need to wait until someone has time, skill and motivation to fix the issue. Instead you chose to harass the maintainer, which is a really bad way to make things happen. (Hint: As soon as a person tries to press me in doing something or just claims that this obviously is broken and needs to be fixed by me now I likely stop doing anything there for self protection for some time). Given these facts it's just not helpful to have you repeated posts complaining about documentation and guides here. If you don't stop with that I block you from the organization as well, as this just takes more time away from work that could be done otherwise. |
Beta Was this translation helpful? Give feedback.
-
Your Acknowledgement
Thank you! I am glad you finally acknowledge that significant issue. Late is better than never. All I am asking you for the next times, instead of insulting or degrading our knowledge level, please consider our needs as well without ignoring your own ones. I really appreciate your absolutely understandable explanation and your call for assistance (contributions)! I hope we can tackle it - exactly what open source and community projects are about. The beauty of (F)OSS is we can work together and increase our common profit - which in return increases yours. I never pressured you into something. If it feels like pressure, it's soley on your side and indicates we should tackle it. I am pointing out the core issue, which is valid critique and I think blocking me for sound and valid, voiced critique would be a pretty weak response. Better it's me pointing the issue out than others. Think about that perspective. Lacking documentation and Revenue
While I am absolutely fine with your other responsibilities and what ever floats your boat, lacking documentation costs you a lot more (compared to what you would possibly earn) in the end. Insufficient Documentation Lowers Your Reveneue
Example one:
Example two:
Providing sufficient documentation is a well known industry standard, even in Open Source
What's actually needed?I believe:
*Possibly if you want to stick with method-based examples, we need a more narrow focus on CRUD. What I see is a confusing mix of technical concepts (the Rust lingo, the Diesel lingo) and CRUD. The code examples in the Repo making it also difficult to understand what exactly I am looking at and what I need that for. Documentation Size and ExtendNobody wants a perfectly written 300 page document. That's not necessary and would require too much time investment and work. So strike that. Most people, including me, prefer a basic e.g. what we are going to do/solve (introduction), common use-cases, common issues, and how to get things running asap. Allowing us to copy paste basic things and then work from there. So our creativity and fun flows. It allows us to build a work routine, enabling us to help others - consequently reducing your time efforts in the Q&A section. I have often seen a three-level guide, from beginner, intermediate to pro. Not sure if we need that but that could be an idea to satisfy the needs of all. Consider how the general public reads and uses documentationsI think we should consider how the general public reads such documentations and guides. Additional information and better documentation increases the likelihood of good contributions. Nobody reads it all, people skim over text, search for easier explanations and simple tutorials etc. People learn in small steps over time. Too much info and too much effort to get into something literally throws them off and prevents them from contributing. Examples for online tutorials
What prevents a good Quality Management (QM)?Three root-causes preventing contributions in the documents' Quality Management:
ContributionsDefining contributionsDo we have the same understanding what contributing is? If you ask me to increase your business output, that is solely your responsibility, not mine. I already provided actionable feedback, collected or analyzed multiple times where more improvements are needed. I even contributed to it's fixing. Contributions relations to atmosphere and insight (knowledge) levelYou want contributions but at the same time we are getting insulted, degraded or told off, when asking questions, voicing critique or just complaints and contributing. Also, insufficient documentation reduces the insight of the community, consequently reducing the ability to improve the documentation. Like previously shown basic areas are affected, especially the core understanding how to tackle specific issues on our own, the same way we would need a instruction set on how to debug a software of any software company. So a general scheme what should we do first to possibly come to a working solution, maybe even before asking a question. Mentioned points decreasing the likelihood of receiving overall contributions, not just documentation QM related ones. Looks a bit like a chicken-egg problem to me, a bit difficult to tackle but possible. How I already contributedRegarding
I helped establishing a basic overview and some QMI did a first step in actually documenting such issues and highlighting areas where the documentation or guides have weak spots. I went through the Q&A issues which explicitly mention the guide (see above). Gladly, we can appreciate their long-term existence, allowing that kind of collection and analysis of them. I worked on write ups and asked questionsAdditionally, I already wrote a small write up regarding the enum and sqlite issue (see #3742 and https://github.com/ksaadDE/rustgotchas/blob/main/How_to_convert_a_Enum_to_DB_row_string_value_using_Diesel.md) Once provided, you've bashed against the contribution:
Sure, it might not be perfect but it would have been helpful once getting into Diesel. Good enough to get the boat floating. Details are a matter of detail and specifics. Expertise develops over time, while making progress. I would have written another one but sadly my question #3947 was locked, after I was insulted (yet again). It was about implementing a enum-like if condition for multiple columns of a db row on db-level to use the calculated result later on (e.g. result = row.a && row.a && !row.c => 1; result = row.a && !row.b && row.c => 2 etc). Yet again I spent some time to contribute and help out. Like I did with many other projects in my limited spare time. |
Beta Was this translation helpful? Give feedback.
-
|
Little addendum of critique or lacking understandings by others (those are from the web and likely a bit older) :
Someone had issues finding the guide to MyQL Connecting to MySQL was a problem in the past too, seemingly the user had trouble to disable the SSL mode to make the connection
Seemingly the starting guide also caused trouble (due to minimal changes over time? due to misreadings?)
User says they need to get used to the expression stuff Diesel and Windows - ure referring to a bundle in there. First time I have seen this :D Another one has a diesel setup issue but fixed it using a
I had that same question at the beginning "how-to-make-diesel-auto-generate-models" Unlucky user errors in handling Rust (or better to say their env varibales of the OS) are also happening:
User needed five hours to find a wrong order of is_admin and password (error message is about derserialize and uuid) Excellent explanation: "Why does order of fields in struct need to match table? TL;DR: Diesel prefers deserializing by index instead of by name." (even with ref. to the docs!) headache with delete return val How to use upsert + insert_into + on conflict + excluded + AsChangeset
Mapping a postgres view?
How to insert a decimal number with Diesel's PgNumeric type? Not sure if still valid: Creating Diesel.rs queries with a dynamic number of .and()'s How to display the value retrieved using Diesel in HTML using a Tera template in Rocket? As far as I've seen many Questions, misunderstanding and problems can also be extracted from https://stackoverflow.com/questions/tagged/rust-diesel |
Beta Was this translation helpful? Give feedback.
-
|
As you already done all the work to put together this list of things that you personally consider badly documented I would suggest that you contribute to fix these issues. After all that seems to be something that you have feelings about. I personally do not agree about quite a large number of these points, but that's a personal opinion and nothing I would reject better documentation for. Additionally almost all of your links refer to old diesel versions so it's easy to claim that these are still an issue. Would you have spend the time to actual check that, you would have noticed that some significant part of this is already addressed by various "new" features and documentation changes. As written before: Due to other priorities I do not have the capacity for that and I do also not have the motivation to continue this toxic discussion. Consider this my last answer to any of your requests until you fundamentally change your wording and your approach how you interact with this project. You need to understand that there is a fundamental difference between a user of this project and the maintainers, especially if you ask for help. The most significant point there is that you want something from me not the other way around. I do not force you to use my project, nor I'm interested in that you personally use it, while you want to know how to solve your issue from me. |
Beta Was this translation helpful? Give feedback.
-
|
I kindly ask to apologize the miscommunication about my previous questions and suggestions. Generally I only raise questions after spending hours searching for information, ending up frustrated, unable to proceed and then I am only seeking to speed things up. Your maintainer insights and wisdom would have been helpful to enable me to solve my issues on my own, avoiding future questions by telling/showing us how you think in Diesel terms. It would have helped me to convey that knowledge to others. I understand you need more contributions and you prioritize eminent financial aspects to make Diesel more awesome. Reoccurring/"stupid questions" and "lacking contribution" (= wasted time => less money for you) indicating that a few time investments in sufficient documentation are needed. My list might not be sufficient as a good starting point. It lacks the maintainers perspective, organization, structure and internal knowledge. Latter is a reason why we users are yet unable to contribute. Knowledge gaps that I see:
Where do we start? What list/overview? Filling the knowledge gap will likely make your project more public and attract more contributors. |
Beta Was this translation helpful? Give feedback.
-
As show of good will, I went through the past Q&As and made a list of common asked questions. So please take a look at it and understand the pattern, which is not coming from the community. It is clearly a guide issue!
User was told:
So user replied:
User was told:
#4089
User was told "currently no complete guide for select statements" and that all methods for that are document in trait.QueryDsl within the docs.
#2735 #2735 (comment)
User was told "Putting everything behind one derive is just not an option as there are a lot of cases where only a subset of the conversions offered by the different derives are valid or even possible"
#2938 #2938 (comment)
#3030 #3030 (reply in thread)
User was told "That's currently the only way to specify these return types"
#3458 #3458 (comment)
Hard time to generate a equivalent of a SQL statement
#3513 #3513 (comment)
User can't find the best way to update many multiple records with a complex scenario including AsChangeSet and objects using it (not covered in the guide; to find batch queries are not implemented)
#3417 (reply in thread)
#3096 #3096
#2890 #2890 (reply in thread)
custom schemas were not findable in the guide
#2990 #2990
#3162
#3162 (reply in thread)
(with you commenting to another post: "Please consider to take more time to formulate your questions in such a way that they are understandable by other people [unlike the guide xD].")
User was unable to find "Extending Diesel", because user did not know whether "lateral queries" were part of diesel
#3132 (comment)
#4031
Users are often recommended to not implement generic code, as it gets hard to maintain (which probably conflicts with most basic programming best-practices out there). Users should also look up the type defs in the docs for the corresponding methods.
#3968 (comment)
User was told:
Nice to know, I wish the guide/docs would somehow mention that.
#3947
It's just a example, minimal set, obtained from searching for all Q&As containing "guide"! Are all of us "stupid idiots" (see #4089) that can not read your guide nor the RUST documentation properly? 🤔
Beta Was this translation helpful? Give feedback.
All reactions