Reorganize Effection Documentation

[minkimcello]

I was reading through the effection v3 docs and had some ideas on better organizing its content:

Getting Started

This section should be reserved for content that prepares the readers for learning Effection. We want our users to be able to read top down without without having to jump back and forth forward and back so it would make more sense to put Typescript lower as it discusses Operations before it's been introduced, and the same goes for the current fetchWeekDay tutorial in the Tutorial page.

This is also where we can add the new FAQ page (#811).

Learn Effection

In the Learn Effection section, I'm proposing the following changes:

• Add an Overview page - this will be our "How to navigate these docs" page and provide a high level overview of the different components of Effection
• Group guides together by adding dividers - I think the dividers could help give readers a breathing spot in their journey of learning Effection
• Create a single page for race(), sleep(), all(), call(), ensure(), and whatever else
  • I chose Utilities as a placeholder but we can call it something else

Scope

Other than the Overview page, each page should introduce a new API for consistency so I'm still trying to figure out where the best place would be for Scope. We could first introduce the Three Outcomes section of Scope in Operations and sprinkle the rest in as we introduce more APIs. This way users can learn more about scopes incrementally.

TL;DR

I think it would also be very helpful if each page started with a TL;DR that explains when a user needs to use {x}. If we decide to create an Overview page, we could take the short descriptions we write for the high level overview and just paste it into the TL;DR sections.

Tutorials

And in this section, we can put all the How-Tos. I think this place would be the logical place to put Typescript and Error Handling as neither of these pages introduces any new Effection APIs and by the time the readers get to the tutorial section, they will have already read up on main/run, spawn, suspend, and know what an Operation is.

We may want to create a separate section for Examples down the road but I think we can just put everything into Tutorials for now.

[cowboyd]

I love this type of hi-level thinking!

It might help to use this as a consultation for something that has though about how to present documentation https://documentation.divio.com

Documentation System

Find the software documentation system for Divio. Includes comprehensive tutorials, how-to guides, technical reference and explanation. Learn more here.

[taras]

👍 from me for this proposal.

Regarding Scope: there 3 three aspects to it.

1. Operation scope, lexical scope, and the relationship between the two
2. Context - API for consuming operation dependencies from the tree of operation scope rather than lexical scope.
3. useScope is a lower-level utility helpful for bridging the non-structurally concurrent worlds to the structurally concurrent.

@cowboyd it occurred to me while looking at this list that we need a place to talk about Delimited Continuations. Maybe if we have an Advanced Section, we should put it there. We need to explain how operations work for any Effection core contributor, we need to have that information available for people who haven't yet engaged with us. It might be easy enough to record a screen-sharing session where you explain DC.

[minkimcello]

For Delimited Continuations:

The current proposed structure is organized in such a way that we can provide a "top-down" book-like approach:

• Getting Started introduces Effection without getting too technical - this prepares readers on what they can expect to learn and achieve by using Effection.
• Learn Effection gets more technical and teaches readers how to use functions provided by Effection.
• And finally in the Tutorials we provide real life examples on how to build things using what they learned in the previous section.

The biggest consideration I kept in mind while coming up with this structure was minimizing the risk of overwhelming readers, which is why I excluded an Advanced section. It took me 2-3 read-throughs of the current documentation before it started to click. If there are other readers like me, seeing a section for Advanced could potentially scare them off.

To maintain the top-down approach, putting a topic like this under Getting Started will certainly overwhelm readers - even if we were to put a "Caution: This shit is advanced" disclaimer on the top of the page. And it doesn't make sense to put Delimited Continuations under Learn Effection or Tutorials.

One option would be to create a Community or Contributing section at the bottom of the sidebar in a similar way NextJS and Deno did theirs.

Another option would be to just include Delimited Continuation or a link to it from the GitHub README if it's something that's more relevant to contributors of Effection.

🤷🏻‍♀️

[minkimcello]

It might help to use this as a consultation for something that has though about how to present documentation https://documentation.divio.com

So I've read through this, but I think we're playing a slightly different game than a "traditional" library. With a library like MUI or React, it's easier to follow the conventions they lay out.

When we think about Material-UI, they're essentially offering paint brushes of different shapes and sizes. So they can start with a tutorial on how to use one paintbrush (which sets up readers to go on and fetch the thing they need without the need to read the entire docs), explain and illustrate all the paintbrushes they're offering, and provide how-tos on how to paint a duck or a swan. Basically, readers can learn to use Material-UI from any direction they desire.

However, with Effection, the learning journey of it feels more structured and linear. It would be difficult for readers to jump straight to Streams without reading up on Resource first. And it helps to know what an Operation is before learning the basic building blocks of Action, Suspend, Resource.

So this is all a long-winded way of saying it might be difficult for us to separate Tutorials and Explanations as they describe it. For Effection, it might make more sense to combine the two together.

Documentation System

Find the software documentation system for Divio. Includes comprehensive tutorials, how-to guides, technical reference and explanation. Learn more here.

[taras]

Another option would be to just include Delimited Continuation or a link to it from the GitHub README if it's something that's more relevant to contributors of Effection.

We could create CONTRIBUTING.md file and add a link there to a document on Deliminited Continuation. Alternatively, we could just link to the continuations repository and add the information there.

[cowboyd]

Yeah, I think the idea that "Advanced" usage would not include delimited continuations. Neither writing, nor understanding, so in that sense it's not really a use-case. It's more of an architecture. I do think that a section on "internals" might be appropriate where we can talk about:

• delimited continuations
• frames
• context chain

These are all helpful things to know if you are working on Effection itself, but never if you are using it.

[taras]

@cowboyd what do you think about putting this information into the repository rather than the docs site?

[cowboyd]

Yeah, that would be ok with me. Whichever medium works best