The title is a little underwhelming, but this is a very good discussion of potential designs around async streams/iterators in Rust. Definitely worth a read.
Eh. IMO their writing would be so much better if they applied the inverted pyramid[1]. This piece takes 3 paragraphs to get the point of the post. As someone who is interested in Rust, but not sufficiently interested to get into the weeds of every design decision, it makes for frustrating reading.
That sentence gives no indication it is the main point of the post. It refers to a prior post and nowhere does it say anything about the current post. Even if the main point is indeed "the single best thing the Rust project could do for users is stabilize AsyncIterator" this sentence does not help reader understand this.
In the third paragraph it makes three points:
1. This post is rebuttal to another post
2. This post argues in favour of keeping poll_next
3. This post argues that AsyncIterator should be stablized now
This is the first point in the post in which it makes statements about the content of the post, and what I take to be the main points of the post.
Welcome to another holy war. :) Many people, including myself, loathe the inverted pyramid style. [1] [2]
I think most people can agree on these points: we want writing structured in way we can skim _and_ dive into. We all probably agree that using topic sentences, logical organization, headings, structure, and transitions are important.
Reasonable people can disagree on the order in which information is presented. The author has a tough job: striving to know the audience and crafting words suitably.
For technical writing, I prefer a logical order that educates and builds logically. Give me that. I don't want to have to rearrange whatever "importance ordering" an inverted-pyramid-loving author might construct.
Perhaps the core of my perspective is a deeper claim: an author must truly embrace a kind of humility and ignorance.
(1) Humility that readers a skim a lot. Most of the author's words may get less than a glance. Oh well. (2) Ignorance because the author has very little grasp of their audience's knowledge graphs: what I know or don't, what I'm interested in, or what I think is pivotal.
So what to do? Find some kind of conceptual organization that does not fall apart when confronted with empirical variation.
Now, I want to vent just a little more. I really detest journalism pieces that rearrange stories in ways that make it really hard to build up a mental model of what is happening. Of course, I will grant this style can be fun for fiction and dramatization.
At the beginning Boats showed two different traits, for poll and async.
They re-itersted their argumentation for poll after that, but just seeing those two clearly said traits is basically all the background primer a dev should need to begin drawing their own conclusions & evaluating the choices here. Even if you don't fully know rust, it should be possible to see a couple various members emerging from this.
Thank you for your vehement defense; I agree so strongly & it is so great to hear a good defense against imo bad watering down & adulterating. I didn't need or want to be hit over the lead with mass-media journalism. In my view, reasonable coders should be able to take a stab at interpreting at least the basics of what is in the table themselves from that well-illustrated starting place. Then let WithoutBoats re-argue why on one direction.
Which they do excellently, with great framing, by talking about state machines. Which should also be graspable.
I agree with your "deeper claim", which is why I think the inverted pyramid is good for technical content. It tells you up front what the text is about and lets you know if you should invest more time reading it. (It's the structure used in all academic publications for this reason.)
If I was writing this post my intro would be something like (I'm writing this quickly so it won't be elegant, but the structure is in place):
Yosh Wuyt recently posted an argument in favour of moving away from poll_next in the async next project. I disagree with this position. In this post I'm going to argue in favour of keeping poll_next and finalizing AsyncIterator. Specifically, I argue that poll_next has a simpler conceptual model requiring only a single state machine, better supports pinning, and works better with cancellation.
This introduction gives the structure up-front so the reader can quickly decide if they want to continue. This actually makes me more excited to read the post because I like technical details, and this introduction is promising them. In the actual post the introduction doesn't tell me any specifics about what is to come and so does not motivate me to read further.
Wait: it seems that you are not conveying what the inverted pyramid practically entails.
For a reader it means: start at the front, proceed linearly, and stop reading at any point because you what follows will be, by construction, “less important”.
For an editor, therefore, cut wherever you want to meet a space limit.
This premise of ordering by solely by “importance” as defined by the author is fundamentally flawed. It stands in conflict with detailed, logically organized, skimmable writing. (I think this could be proved mathematically by assuming some fairly obvious points about human nature, but that is for another time. The sketch would be: how to optimize the linearization of a topic graph using varying reader {preferences and knowledge graphs} as the metric.)
Again, I’m not disagreeing with topic sentences. That idea is independent.
What I mean is 1) putting the most important things first and 2) adding sufficient signposts to make the structure of the document clear without having to read everything. I think a strict ordering by importance, which would make a document a kind of simultaneous recursive elaboration of all its points, would be unreadable for a document that, like this one, also has an element of explanation. I think this takes the essence of the inverted pyramid, but if you want to take a definition that is stricter then I'm fine to concede it's not.
Without.boats continues to just operate on such a great level.
These blog posts are so nicely dual audience targeting: they build a specific narrow case for where to go, what to do, that targets the Rust language folks having these discussions on mailing lists. But they also inform & set context, to make the information generally accessible. Having not only the internal focus, but also an external focus feels like a superpower for your argumentation.
That ability to rise above the mailing list experts-only context & to host a broader stage feels so powerful to me. Most of us wont get a digest of whats going on on the mailing lists & in hallway chats in Rust world. But we'll see what wb argued, and think about it, and remember these options if something else does happen. Technical blogging is so excellent.
Many (most?) disagree with this line of thinking, but I believe the "Rust will never have a 2.0" style thought is what ultimately leads these multi-year pursuits of perfect (or at least good enough to last "essentially forever"). The Editions provider a certain release valve for some styles of breaking changes, but I don't believe it's quite enough ultimately over the entire lifespan of a language which will undoubtedly grow cruft that even Editions cannot remove.
it also doesn't help that the fix for the increased difficulty in implementing AsyncIterator for devs (assuming the approach advocated for in the OP winds up being the one selected by the language team) relies on the as yet (?) unstabilized generators/async generators feature. I'm not really why it's not available yet as the necessary compiler features are already in place and have been for years but because it's not, this is kind of a hard pill to swallow.
I would certainly agree that it is a pressure in that direction. But like anything, you take the design constraints you have, and do the best you can with them. Paralysis is not the only possible outcome. Accepting that nothing is ever perfect, that you will make mistakes and then have to deal with it later, and that's okay, is another. There are many instances of the latter happening over the history of Rust's development in the past. It would be nice if the Project could figure out how to strike that balance again.
There are two ways to take it, "Rust will never have a 2.0 ... therefore everything added to it must be perfect." or "Rust will never have a 2.0 ... so don't try to force it to be something that its not and lets make Rust the best it can be."
A language with Rust's priorities but designed with an effect system from the start could be epic. But Rust is not that language and maybe it can't be. And that's ok. We can give Rust a pass since effect systems weren't even invented yet when it was being designed.
> I believe the "Rust will never have a 2.0" style thought is what ultimately leads these multi-year pursuits of perfect
probably, but if it had instead had a "Rust will break your code once a year/biyear" style thought then it likely would have been yet another nice ML-y language no one cared about.
24 comments
[ 4.2 ms ] story [ 51.6 ms ] thread[1]: https://owl.purdue.edu/owl/subject_specific_writing/journali...
I'm not following at all. I'm curious: what do you think the "point of the post" is?
Here is the first sentence:
> In my previous post, the single best thing the Rust project could do for users is stabilize AsyncIterator.
This is indeed the central point of the post. The rest of it explains the why.
In the third paragraph it makes three points:
1. This post is rebuttal to another post
2. This post argues in favour of keeping poll_next
3. This post argues that AsyncIterator should be stablized now
This is the first point in the post in which it makes statements about the content of the post, and what I take to be the main points of the post.
I think most people can agree on these points: we want writing structured in way we can skim _and_ dive into. We all probably agree that using topic sentences, logical organization, headings, structure, and transitions are important.
Reasonable people can disagree on the order in which information is presented. The author has a tough job: striving to know the audience and crafting words suitably.
For technical writing, I prefer a logical order that educates and builds logically. Give me that. I don't want to have to rearrange whatever "importance ordering" an inverted-pyramid-loving author might construct.
Perhaps the core of my perspective is a deeper claim: an author must truly embrace a kind of humility and ignorance. (1) Humility that readers a skim a lot. Most of the author's words may get less than a glance. Oh well. (2) Ignorance because the author has very little grasp of their audience's knowledge graphs: what I know or don't, what I'm interested in, or what I think is pivotal.
So what to do? Find some kind of conceptual organization that does not fall apart when confronted with empirical variation.
Now, I want to vent just a little more. I really detest journalism pieces that rearrange stories in ways that make it really hard to build up a mental model of what is happening. Of course, I will grant this style can be fun for fiction and dramatization.
[1] https://redpenofdoom.com/2012/01/21/why-the-inverted-pyramid...
[2] https://johnkrolldigital.com/2014/09/death-inverted-pyramid-...
They re-itersted their argumentation for poll after that, but just seeing those two clearly said traits is basically all the background primer a dev should need to begin drawing their own conclusions & evaluating the choices here. Even if you don't fully know rust, it should be possible to see a couple various members emerging from this.
Thank you for your vehement defense; I agree so strongly & it is so great to hear a good defense against imo bad watering down & adulterating. I didn't need or want to be hit over the lead with mass-media journalism. In my view, reasonable coders should be able to take a stab at interpreting at least the basics of what is in the table themselves from that well-illustrated starting place. Then let WithoutBoats re-argue why on one direction.
Which they do excellently, with great framing, by talking about state machines. Which should also be graspable.
If I was writing this post my intro would be something like (I'm writing this quickly so it won't be elegant, but the structure is in place):
This introduction gives the structure up-front so the reader can quickly decide if they want to continue. This actually makes me more excited to read the post because I like technical details, and this introduction is promising them. In the actual post the introduction doesn't tell me any specifics about what is to come and so does not motivate me to read further.For a reader it means: start at the front, proceed linearly, and stop reading at any point because you what follows will be, by construction, “less important”.
For an editor, therefore, cut wherever you want to meet a space limit.
This premise of ordering by solely by “importance” as defined by the author is fundamentally flawed. It stands in conflict with detailed, logically organized, skimmable writing. (I think this could be proved mathematically by assuming some fairly obvious points about human nature, but that is for another time. The sketch would be: how to optimize the linearization of a topic graph using varying reader {preferences and knowledge graphs} as the metric.)
Again, I’m not disagreeing with topic sentences. That idea is independent.
These blog posts are so nicely dual audience targeting: they build a specific narrow case for where to go, what to do, that targets the Rust language folks having these discussions on mailing lists. But they also inform & set context, to make the information generally accessible. Having not only the internal focus, but also an external focus feels like a superpower for your argumentation.
That ability to rise above the mailing list experts-only context & to host a broader stage feels so powerful to me. Most of us wont get a digest of whats going on on the mailing lists & in hallway chats in Rust world. But we'll see what wb argued, and think about it, and remember these options if something else does happen. Technical blogging is so excellent.
Seems really weird, pinning is not an effect, if anything it suppresses an effect (move).
Edit: I guess i should have kept reading the next paragraph, where he touches on a `Move` trait.
A language with Rust's priorities but designed with an effect system from the start could be epic. But Rust is not that language and maybe it can't be. And that's ok. We can give Rust a pass since effect systems weren't even invented yet when it was being designed.
probably, but if it had instead had a "Rust will break your code once a year/biyear" style thought then it likely would have been yet another nice ML-y language no one cared about.