Stream: wg-async-foundations

Topic: async book


Taylor Cramer (May 28 2019 at 17:58, on Zulip):

o/ @Yoshua Wuyts

Taylor Cramer (May 28 2019 at 18:00, on Zulip):

one thing that would be tremendously helpful that I haven't had the time to investigate is a way to set up the book so that we can actually reference sections of code from the docs that is actually getting run and tested in CI, to ensure that we can make changes and edit with confidence that the code still compiles

Taylor Cramer (May 28 2019 at 18:00, on Zulip):

I know there are a variety of solutions to this in the wild, but I'm not familiar with that space

nikomatsakis (May 28 2019 at 18:08, on Zulip):

@Taylor Cramer is it an mdbook?

nikomatsakis (May 28 2019 at 18:08, on Zulip):

If so, it's pretty easy

Taylor Cramer (May 28 2019 at 18:22, on Zulip):

@nikomatsakis currently it's just a set of markdown files, or it was when I last touched it

Taylor Cramer (May 28 2019 at 18:23, on Zulip):

but that sounds like a great change to make ;)

Yoshua Wuyts (May 29 2019 at 10:30, on Zulip):

Ohey, I didn't get a notifcation for this. Thanks for making this channel @Taylor Cramer!

Yoshua Wuyts (May 29 2019 at 10:38, on Zulip):

I guess I was wondering about two things:

Yoshua Wuyts (May 29 2019 at 10:38, on Zulip):

1. how do we present the book to the public?

Yoshua Wuyts (May 29 2019 at 10:39, on Zulip):

2. how do we schedule & contribute content so by mid-August we have a solid reference the rust community can use?

Yoshua Wuyts (May 29 2019 at 10:41, on Zulip):

Regarding presentation -- currently the book is under rust-lang/async-book. Similar to rust-lang/book, but different from rust-wasm/book and rust-cli/book.

Yoshua Wuyts (May 29 2019 at 10:43, on Zulip):

There's also a wider conversation happening on whether the domain books should be bundled with rustup doc, and/or how to present them online -- currently the entrypoint for most people would be https://www.rust-lang.org/learn

Yoshua Wuyts (May 29 2019 at 10:44, on Zulip):

I was thinking that perhaps a good way to get people to contribute / manage the async-book would be if it could live as part of rustasync/book, as a counterpart to rustwasm/book and rust-cli/book (which might get renamed to rustcli/book at some point too).

Yoshua Wuyts (May 29 2019 at 10:45, on Zulip):

Which ties into question 2: How do we plan the content for async-book?

Yoshua Wuyts (May 29 2019 at 10:51, on Zulip):

I feel the current outline is really good! Folks in the async eco wg have expressed interest in contributing; I was thinking if perhaps we could make this a regular part of the meetings so we can make steady progress on it, week over week.

Yoshua Wuyts (May 29 2019 at 10:52, on Zulip):

I think with the current outline we could hit that goal quite easily ^^.

Yoshua Wuyts (May 29 2019 at 10:52, on Zulip):

Yoshua Wuyts (May 29 2019 at 10:53, on Zulip):

Anyway, I feel like I've typed a lot this morning, haha. That's all I had! -- keen to hear thoughts!

Yoshua Wuyts (Jun 04 2019 at 17:48, on Zulip):

ping @Taylor Cramer I'd love to get your thoughts on ^

Taylor Cramer (Jun 04 2019 at 17:49, on Zulip):

hey!

Taylor Cramer (Jun 04 2019 at 17:51, on Zulip):

1) not sure what presentation you had in mind, but I think nmatsakis's suggestion to make it an mdbook was a good one, get a copy hosted, link it from the futures-rs docs as well as potentially the main rust site
2) having a regular checking and creating tracking issues are probably good first steps. does meeting 30 minutes before the main async foundations wg meeting work for you?

Taylor Cramer (Jun 04 2019 at 17:51, on Zulip):

WRT planning content: yeah, I think the current table-of-contents reflects my own opinion, and if folks have other sections they feel like contributing I think the right step would be to open issues and we could triage them in our weekly meeting

Taylor Cramer (Jun 04 2019 at 17:52, on Zulip):

@Yoshua Wuyts does that roughly match your expectations?

Yoshua Wuyts (Jun 04 2019 at 17:55, on Zulip):

@Taylor Cramer it does!

Yoshua Wuyts (Jun 04 2019 at 17:55, on Zulip):

meeting 30 mins before sounds good! -- is there a way we could put that on the calendar?

nikomatsakis (Jun 04 2019 at 17:56, on Zulip):

my only comment on the outline is that I think it might make sense to do a bit more "high-level" material before diving into the futures trait details

Taylor Cramer (Jun 04 2019 at 17:56, on Zulip):

Cool! I'll start making and assigning some issues today, and we can start divvying up work. Yeah, although the compiler team calendar is kind of a funny bbit

Taylor Cramer (Jun 04 2019 at 17:57, on Zulip):

@nikomatsakis there's some of that in the introduction and the initial async/await example, but those could be expanded. Is there some specific content you were hoping to cover in that?

nikomatsakis (Jun 04 2019 at 17:57, on Zulip):

I can give you perms to edit compiler/lang team calendars

Yoshua Wuyts (Jun 04 2019 at 17:57, on Zulip):

I'll let async eco WG memebers know about this too; there has been interest in contributing for a while

Taylor Cramer (Jun 04 2019 at 17:57, on Zulip):

@nikomatsakis that would be great!

nikomatsakis (Jun 04 2019 at 17:57, on Zulip):

I think it may be more a matter of rearranging the table of contents

Taylor Cramer (Jun 04 2019 at 17:57, on Zulip):

@Yoshua Wuyts awesome! glad to hear it

Taylor Cramer (Jun 04 2019 at 17:57, on Zulip):

@nikomatsakis makes sense

nikomatsakis (Jun 04 2019 at 17:58, on Zulip):

i.e., the async-await primer section is close to what I was thinking, but I might pull it out to a more prominent chapter

nikomatsakis (Jun 04 2019 at 17:58, on Zulip):

I kind of glazed over it at first, just looking at the "major headings"

nikomatsakis (Jun 04 2019 at 17:58, on Zulip):

I'd probably incorporate the runtime crate so that you can have an async fn main and walk through some kind of thing like the guessing game

nikomatsakis (Jun 04 2019 at 17:58, on Zulip):

which is quite trivial but also complex enough to be interesting

nikomatsakis (Jun 04 2019 at 17:59, on Zulip):

I guess that is roughly what is happening in Applied: HTTP Server

nikomatsakis (Jun 04 2019 at 18:00, on Zulip):

so maybe it's mostly a matter of calling attention to what's there -- I was thinking a heading like

"Writing code with async-await"

which sounds a bit less "beginner and boring" than "Getting started" :)

nikomatsakis (Jun 04 2019 at 18:00, on Zulip):

but i'm not sure, maybe I'm just wrong

Taylor Cramer (Jun 04 2019 at 18:01, on Zulip):

@nikomatsakis yeah, although there's a dedicated async/await! chapter later on that goes into more details

nikomatsakis (Jun 04 2019 at 18:01, on Zulip):

yeah, I guess i'm debating how much depth to go into before tackling the futures trait

Taylor Cramer (Jun 04 2019 at 18:02, on Zulip):

My opinion has always been "not that much", as it's really helpful to understand in order to use async/await correctly. It's a very leaky abstraction.

Taylor Cramer (Jun 04 2019 at 18:03, on Zulip):

(and FWIW the coworkers i've had who learned async/await without learning the Future trait first have reported that they had some confusions as a result)

Yoshua Wuyts (Jun 04 2019 at 18:07, on Zulip):

Put it on the eco WG agenda!

nikomatsakis (Jun 04 2019 at 18:07, on Zulip):

Interesting.

nikomatsakis (Jun 04 2019 at 18:07, on Zulip):

I'd definitely be curious to hear more details

Yoshua Wuyts (Jun 04 2019 at 18:07, on Zulip):

(I've got to run again; talk to y'all offline / next week!)

nikomatsakis (Jun 04 2019 at 18:07, on Zulip):

It seems likely that we have to teach some parts of the model but I feel like you should not have to learn about (e.g.) Pin in order to get productive work done

Taylor Cramer (Jun 07 2019 at 21:37, on Zulip):

@nikomatsakiswhen you get a chance, can you either add an event for async-book-meeting or give me permissions to edit the calendar?

nikomatsakis (Jun 10 2019 at 21:26, on Zulip):

@Taylor Cramer done -- you should be able to edit calendar

Taylor Cramer (Jun 10 2019 at 21:41, on Zulip):

@nikomatsakis great, added a book meeting event

tinaun (Jun 10 2019 at 23:34, on Zulip):

where is the calendar?

nikomatsakis (Jun 11 2019 at 16:15, on Zulip):

@tinaun https://github.com/rust-lang/compiler-team#meeting-calendar

Taylor Cramer (Jun 11 2019 at 16:31, on Zulip):

howdy, all!

Taylor Cramer (Jun 11 2019 at 16:31, on Zulip):

update on book things:

Taylor Cramer (Jun 11 2019 at 16:32, on Zulip):

I've gotten link checker running on the book and am working to pull out the example code into separate projects in an examples/ workspace inside the async book repo, update those to the current library/syntax, and get tests running in CI. Once that's done, it should be easier to start accepting PRs for new content.

Taylor Cramer (Jun 11 2019 at 16:33, on Zulip):

If anyone wants to start working on content, feel free to take a look at the table of contents: https://github.com/rust-lang/async-book/blob/master/src/SUMMARY.md, and open an issue mentioning that you plan to get started

Taylor Cramer (Jun 11 2019 at 16:33, on Zulip):

there's a lot there left TODO, and I'll aim to have a PR up today with the examples and everything factored out so we can get started

nikomatsakis (Jun 11 2019 at 16:34, on Zulip):

@Taylor Cramer (queston -- did you mean to start a "meeting topic"?)

nikomatsakis (Jun 11 2019 at 16:34, on Zulip):

(or shall I?)

Taylor Cramer (Jun 11 2019 at 16:35, on Zulip):

@nikomatsakis I did not, since currently "async book" was its own topic and I was hoping to notify the people already in this topic

Taylor Cramer (Jun 11 2019 at 16:35, on Zulip):

but perhaps "async book" should be made into its own stream

Taylor Cramer (Jun 11 2019 at 16:35, on Zulip):

so that we can have subtopics within it

nikomatsakis (Jun 11 2019 at 16:35, on Zulip):

yeah

nikomatsakis (Jun 11 2019 at 16:35, on Zulip):

I can create a #wg-async-foundations/book if you like

Taylor Cramer (Jun 11 2019 at 16:35, on Zulip):

that would be great!

nikomatsakis (Jun 11 2019 at 16:36, on Zulip):

Done: #wg-async-foundations/book

Last update: Nov 18 2019 at 01:05UTC