oh yes, tide looks really nice but I don't think it will in 1.0 any time soon, but I may be wrong, strangely Rust projects seems to advance really fast, I don't know if is just my impression, but sometimes really surprises me. Actix, Diesel, SQLx, one day is bare, almost nothing and the next month they are packed with goodies, stable and polished. Maybe is the safe feeling of Rust and that they don't spend too much time documenting and making tutorials and alike, once you get used to it you just go straight to the API docs (that are made automagically), I love that too, just reading the API docs you learn Rust.
Maybe is the safe feeling of Rust and that they don't spend too much time documenting and making tutorials and alike...
Actually, I find that a little alarming, @robertorojasr
. Even if Rust is the most obvious, straightforward language in the world (which it isn't, at least to me, and that still counts), a lack of documentation always comes back to bite a community.
Case-in-point, Python is famous for being obvious in most cases, often even more so than Rust, but the community didn't take that for granted and wrote the documentation anyway. And it's a good thing. We get no end of "obvious" questions in #python, not because the language is so bad or the topic is so murky, but because its entirely too easy to overestimate how obvious something is based on our own technical biases.
I actually don't know that I agree with that characterization of the ecosystem outside of brand-new tools that are just starting to see the light like SQLx, and these will catch up eventually if they catch on. In general, I've found Rust core tools and established ecosystem tools to have a very robust, high-quality documentation culture even relative to more established languages. On the contrary, this culture one of the big draws for me.
It's a new language, so there are inevitably gaps, but it's a time issue. I haven't personally felt there's any false sense of security created by Rusts's semantics in this regard. The false sense of security is around what "unsafe" means in the first place, but that's a separate issue :)
maybe that's what has slowed its wide adoption, maybe it also has something to do with my impression that most projects seem to be solo projects (made by 1 or maybe 2 guys); perhaps is because of how new is the ecosystem? I haven't follow a language so young before. Is also worth noticing that even in Python not everything started thoroughly documented, it was a process, when I talk about documentation here, I'm excluding the more technical API docs, those are usually very complete, filled with useful examples, for the standard Rust libraries I never felt the need for something besides The Book and the API docs; when I talk about "documentation" I'm wrongly refering to extras, like tutorials, step by step guides and alike. And those where scarse at best with Flash, SQLAlchemy and even Django always had a very good documentation but at first lack many important topics and many features went undocumented for a long time, with the years have been improved a lot.
We must also notice that Rust is not it's web frameworks and the language didn't aimed to web devs, so documentation is more "technical", there are also web frameworks in C and C++, and don't have all those extra documents either, but to say that C has poor documentation is a stretch.
I also think that, like any other document, it has it's group target, of course if you compare the documentation of Django with Diesel for example, Diesel is light years away, but if you compare SQLAlchemy (a few years ago, I don't know about it now) with Diesel, Diesel's in not bad at all, with the difference that Diesels API docs are awesome and every single thing is documented. Of course the target audience for Django is not the same as Flask, Diesel, SQLAlchemy or Rocket; and Rust doesn't have a Django yet.
it's web frameworks and the language didn't aimed to web devs, so documentation is more "technical"
I'd say it isn't any more "technical" than Javascript docs are. Yet Javascript docs may feel "technical" to a desktop application developer such as myself, since the industry sector is unfamiliar.
Documentation is geared towards the target audience of the language. Tutorials (and books) are how someone new to the programming sector onboard, mainly because they need to be taught the fundamental paradigms, patterns, and concepts of the sector. Someone already in that sector likely needs no such introduction; a Java developer is right at home with the C++ documentation, a C++ developer with Rust documentation, and a Rust developer with Java documentation. They're operating in the same sector.
I think I misspoke (misswrote?) before, my point was that I've found that in Rust API docs are not bare or just enough to say you documented; for I've seen in Rust API docs are taken seriously and are closer to Python official documentation that a document just for the dev team. Documentation usually is not a separate thing, that someone else does, is closer to the code in the sense that is never out of date and if there is code there is documentation, there are not undocumented bits. I couldn't survive by Django documentation alone, even tho is amazing there was a lot of features undocumented, a lot of times I had to check in the code itself for some edge cases 3rd party docs: tutorials, guides, etc. where frequently necessary; even more so with Flask and SQLAlchemy. That hasn't happen to me with Rust so far.
I couldn't survive by Django documentation alone, even tho is amazing there was a lot of features undocumented, a lot of times I had to check in the code itself for some edge cases 3rd party docs
That's a failing of Django documentation, not indicative of a merit of Rust's. ;)
I'd say it isn't any more "technical" than Javascript docs are to a desktop
That's why I used quotes, I couldn't find a better adjective.
That's a failing of Django documentation, not a merit of Rust's.
Was not meant as that, just an example to illustrate that even the better documented SW has it's flaws, those doesn't make them badly documented. Which is of course subjective at some point. And if you read until the end of the paragraph
That hasn't happen to me with Rust so far.
Clearly I mention Django to illustrate the difference to me between both and that Django is more friendly to newcomers yet somehow incomplete and Rust more complete yet maybe less inviting to newcomers. That's what I meant to target audience.
Tutorials (and books)
That's what I mistakenly called Documentation before in opposition to API docs which obviously are documentation too. Of course you need documentation, nobody will use a library and even less a framework looking nothing but the code, that would be insane. Not even if the library is only for consumption of the author, not if expect to maintain some sanity.
the interesting thing is, English is my second language, and that shows how, when you are not comfortably enough with the language you end up "coding" big convoluted responses to explain something simple. And misunderstandings happen. And then you try to solve it with more comments. haha, so meta. :D
most projects seem to be solo projects (made by 1 or maybe 2 guys); perhaps is because of how new is the ecosystem?
I think this is exactly right.
for the standard Rust libraries I never felt the need for something besides The Book and the API docs
I agree - these resources are done extremely well, to the point of replacing supplementary material I've needed getting up to speed in other environments.
when I talk about "documentation" I'm wrongly referring to extras, like tutorials, step by step guides and alike
I have also found that there's less of this type of documentation in general, but when it does exist it tends to be high quality, and like you say the fall-back API docs are great too. Diesel is a great example, I think their getting started page is well done and they provide other guides too, but it took time to produce after publishing the crate due to bandwidth.
In general, I've found Rust core tools and established ecosystem tools to have a very robust, high-quality documentation culture even relative to more established languages.
Whew. From the other comment, I was getting reeeeeally worried.
Not on stable. I think I've linked it before in a previous thread with you but my sights are on tide - once it reaches 1.0.
oh yes, tide looks really nice but I don't think it will in 1.0 any time soon, but I may be wrong, strangely Rust projects seems to advance really fast, I don't know if is just my impression, but sometimes really surprises me. Actix, Diesel, SQLx, one day is bare, almost nothing and the next month they are packed with goodies, stable and polished. Maybe is the safe feeling of Rust and that they don't spend too much time documenting and making tutorials and alike, once you get used to it you just go straight to the API docs (that are made automagically), I love that too, just reading the API docs you learn Rust.
Even just making mistakes. I learned how to properly use
Arc<RwLock<T>>largely from compiler errors, suggestions, and lints.Actually, I find that a little alarming, @robertorojasr . Even if Rust is the most obvious, straightforward language in the world (which it isn't, at least to me, and that still counts), a lack of documentation always comes back to bite a community.
Case-in-point, Python is famous for being obvious in most cases, often even more so than Rust, but the community didn't take that for granted and wrote the documentation anyway. And it's a good thing. We get no end of "obvious" questions in
#python, not because the language is so bad or the topic is so murky, but because its entirely too easy to overestimate how obvious something is based on our own technical biases.Design so that documentation is redundant. But then document anyway. "Most API documentation is like teaching someone how to use a toaster by explaining the electrical specifications of the heating element."
I actually don't know that I agree with that characterization of the ecosystem outside of brand-new tools that are just starting to see the light like SQLx, and these will catch up eventually if they catch on. In general, I've found Rust core tools and established ecosystem tools to have a very robust, high-quality documentation culture even relative to more established languages. On the contrary, this culture one of the big draws for me.
It's a new language, so there are inevitably gaps, but it's a time issue. I haven't personally felt there's any false sense of security created by Rusts's semantics in this regard. The false sense of security is around what "unsafe" means in the first place, but that's a separate issue :)
maybe that's what has slowed its wide adoption, maybe it also has something to do with my impression that most projects seem to be solo projects (made by 1 or maybe 2 guys); perhaps is because of how new is the ecosystem? I haven't follow a language so young before. Is also worth noticing that even in Python not everything started thoroughly documented, it was a process, when I talk about documentation here, I'm excluding the more technical API docs, those are usually very complete, filled with useful examples, for the standard Rust libraries I never felt the need for something besides The Book and the API docs; when I talk about "documentation" I'm wrongly refering to extras, like tutorials, step by step guides and alike. And those where scarse at best with Flash, SQLAlchemy and even Django always had a very good documentation but at first lack many important topics and many features went undocumented for a long time, with the years have been improved a lot.
We must also notice that Rust is not it's web frameworks and the language didn't aimed to web devs, so documentation is more "technical", there are also web frameworks in C and C++, and don't have all those extra documents either, but to say that C has poor documentation is a stretch.
I also think that, like any other document, it has it's group target, of course if you compare the documentation of Django with Diesel for example, Diesel is light years away, but if you compare SQLAlchemy (a few years ago, I don't know about it now) with Diesel, Diesel's in not bad at all, with the difference that Diesels API docs are awesome and every single thing is documented. Of course the target audience for Django is not the same as Flask, Diesel, SQLAlchemy or Rocket; and Rust doesn't have a Django yet.
I'd say it isn't any more "technical" than Javascript docs are. Yet Javascript docs may feel "technical" to a desktop application developer such as myself, since the industry sector is unfamiliar.
Documentation is geared towards the target audience of the language. Tutorials (and books) are how someone new to the programming sector onboard, mainly because they need to be taught the fundamental paradigms, patterns, and concepts of the sector. Someone already in that sector likely needs no such introduction; a Java developer is right at home with the C++ documentation, a C++ developer with Rust documentation, and a Rust developer with Java documentation. They're operating in the same sector.
I think I misspoke (misswrote?) before, my point was that I've found that in Rust API docs are not bare or just enough to say you documented; for I've seen in Rust API docs are taken seriously and are closer to Python official documentation that a document just for the dev team. Documentation usually is not a separate thing, that someone else does, is closer to the code in the sense that is never out of date and if there is code there is documentation, there are not undocumented bits. I couldn't survive by Django documentation alone, even tho is amazing there was a lot of features undocumented, a lot of times I had to check in the code itself for some edge cases 3rd party docs: tutorials, guides, etc. where frequently necessary; even more so with Flask and SQLAlchemy. That hasn't happen to me with Rust so far.
That's a failing of Django documentation, not indicative of a merit of Rust's. ;)
That's why I used quotes, I couldn't find a better adjective.
Was not meant as that, just an example to illustrate that even the better documented SW has it's flaws, those doesn't make them badly documented. Which is of course subjective at some point. And if you read until the end of the paragraph
Clearly I mention Django to illustrate the difference to me between both and that Django is more friendly to newcomers yet somehow incomplete and Rust more complete yet maybe less inviting to newcomers. That's what I meant to target audience.
That's what I mistakenly called Documentation before in opposition to API docs which obviously are documentation too. Of course you need documentation, nobody will use a library and even less a framework looking nothing but the code, that would be insane. Not even if the library is only for consumption of the author, not if expect to maintain some sanity.
Aha, following you now. :)
the interesting thing is, English is my second language, and that shows how, when you are not comfortably enough with the language you end up "coding" big convoluted responses to explain something simple. And misunderstandings happen. And then you try to solve it with more comments. haha, so meta. :D
TODO list:
I think this is exactly right.
I agree - these resources are done extremely well, to the point of replacing supplementary material I've needed getting up to speed in other environments.
I have also found that there's less of this type of documentation in general, but when it does exist it tends to be high quality, and like you say the fall-back API docs are great too. Diesel is a great example, I think their getting started page is well done and they provide other guides too, but it took time to produce after publishing the crate due to bandwidth.
Whew. From the other comment, I was getting reeeeeally worried.
If it didn't I wouldn't have stuck around. Who has that kind of time?