Organization of the readme

[codehag]

Hi,

I was asked to take a look at the mental model in another issue, and it was the first time I looked at this in depth. I have to say, coming from the perspective of someone completely new to this, I found it quite hard to understand what this repository is trying to describe.

Going through the proposal, here are my comments where I found myself tripping up, and going up and down the document to find answers.

• the proposal repo is named eventual send but the headline is Promise.delegate
• the problem statement is not stated. A summary of the use cases and the difficulties associated with them would help a lot.
• Reading the background was more confusing than enlightening, I think it would make more sense when I had a clear grasp of the problem without reference to other languages that have their own histories. The background is interesting, but not critical and actually quite confusing. I would move it into it's own md file to be referenced.
• the details section starts talking about Proxies right away, which is going to be really hard for people who are not familiar with proxies. I think it is worth while making the connection (and link! maybe to a dedicated document?), but it is also going to be a good idea to describe things without reference to proxies.
• the readme starts talking about promise.delegate here but we so far have no idea what it is. It is only sort of described way later, here about 2/3rds of the way into the document. Even there, it is unclear to me how this api fully works. For example, if unfulfilledHandler is defined, what does it look like? In eventualGet, what is the type of the arguments? We know the type of the returns..
• the eventual* methods are spread over the readme and I could not clearly understand the different sections. Same for the proxy stuff, it is hard to see how the different sections are organized or what they are trying to tell me.
• the platform support section was surprising to me, as it didn't list platforms, but a specific issue in one platform. I would expect a list of implementations here. I think what is described here is ... partially a problem being solved by the proposal? This may very well be the problem section if it is reworked a bit?
• there are a lot of references to proxy handlers. I think it makes sense in some cases, especially promise.delegate to fully explain what that means locally.

Broadly, for a reorganization that would help someone like me understand where to start with this proposal, I would suggest this as a broad structure. It is what would have helped me orient myself:

Introduction A quick way to grasp the proposal.

• basic at a glance process info, like stage, champions, and authors
• Problem statement, 3-4 sentences describing what could be solved
• Motivating Usecase(s): who will use this and how will it make it possible for them to do something, or make it easier to do something. A short list, maybe just one thing, maybe more. If it is a lot, link out to a separate document. If you make it a separate document, you can also show how these examples will be solved in tandem with each example. But this needs to be short in the readme, so that people are not overwhelmed by information.
• Summary of solution: One paragraph (the one you have might work)

API overview

• list of APIs, organized starting from apis that can be used in isolation, and building up to complementary methods. Kind of what you did in the "details" section but reorganized to start with Promise.delegate, and with less detail. Possibly split the details into a dedicated readme that is linked from this section. As you build complexity, link back to the motivating examples or to the problem statement to show how each piece fits into the goal. Basically, give people a walk through about how each of these pieces fits together. You can introduce the wavy-dot syntax as part of this section, as you build up the complexity.

Implementations

• list of shims / implementations so far, and limitations (if there are any) -- keep to short, bullet point items.

Prior Art

• Previous work done in this area. I think maybe RPC? or Unison? I am not sure though
• Also a good section for background. Again, it needs to be shorter, but can link out to a longer document.