Content Structure

[mikearnaldi]

This issue to begin discussion of the content structure of the website, I think we should pause accepting PRs and remove current content until the structure is agreed and we have a baseline.

The reason is fairly simple, while all the content may look good in small it hardly make any sense as a whole, for example:

• https://www.effect.website/docs/core-concepts/option
• https://www.effect.website/docs/core-concepts/either
• https://www.effect.website/docs/advanced-concepts/types

While each page may look nice if one is reading precisely about that topic none of it is any relevant to learning Effect, reading through the details of the page Option & Either there is twice the explainer of the map function, conceptually it shouldn't be there in the first place.

Starting with the purpose of the website doc, the website doc is meant to approach beginners and experts alike, it should be a beginning guide into the world of effect and not a replacement of reference docs, if I want to know all the typeclasses that are available in effect the place is https://effect-ts.github.io/data/modules, if I am looking at the website I want to understand the concepts and the "what's best".

I am by no mean a content writer but I'll start with a proposed structure:

- Core Concepts
  - Effect
  - Errors 
  - Services
  - Layers
  - Runtime
  - Batching & Caching
  - Logging
  - Metrics
  - Configurations
  - Testing
  - Schemas
  - Immutability
  - Equality

- Utility Modules
  - Option
  - Either
  - HashMap
  - HashSet
  - Chunk
  - ...

- Deep Dive
  - Cache
  - Cause
  - Deferred
  - Exit
  - Fiber
  - FiberRef
  - Pool
  - Scope
  - Queue
  - Hub
  - Random
  - Clock
  - ...

Each module should introduce the concepts as new and should focus on articulating:

• why should I use this module?
• when should I use this module?
• how should I use this module?

• where can I look for further references?

  Generally I'd like to avoid copying from any pre-existing doc attempt (let it be in fp-ts repo or in my blog posts) and rather focus on producing something new thinking that we need to explain those concepts to a person who potentially doesn't even know TS well or else programming in any serious manner

[aniravi24]

I agree with this sentiment. I don't really think the stuff that was ported from fp-ts has a good place in the docs yet, and shouldn't have been included without clarity on where it should be (if at all).

For the core concepts, at minimum, I initially planned to have at least these topics.

1. creating effects
2. running effects
3. error handling
4. services
5. layers
6. scope
7. runtime

I think usages of scope (e.g. acquireRelease, etc.) should be included before runtime.

I think some of the core concepts you mentioned could be in a separate section - not sure what to call it, but it would live somewhere between core concepts and deep dive.

I like the questions that each page should seek to answer.

I'm not totally sure what kind of content you're envisioning under some of those topics (e.g. immutability and equality), so once we find a structure we can agree on, we can dive more into what to cover.

I agree that we should avoid copying from pre-existing doc attempts and try to produce something new. We can look for more inspiration from other sources later, rather than letting those attempts bias our initial ideas.

[jessekelly881]

This structure looks really great! I'm looking forward to it being fleshed out so that I can stop asking you guys random questions on the discord. jaja. I think the fp-ts docs are super important to have though, even if it's just there as a reference. If the concepts are going to be mentioned in the docs or at least used within the codebase, they should be explained somewhere within the docs, even if it is buried. That way they are searchable at a minimum. They definitely need moved though, they are really out of place where they are now.

That said though(warning, opinions ahead)..., I don't think they should be buried. fp-ts presents a ton of concepts that are super valuable on their own and I feel like they deserve a front and center explanation. Option/Either and Effect are kind of two sides of the same coin and are both super useful in different circumstances. It feels like a real shame to burry them when lots of people have benefited from fp-ts on it's own.

[mikearnaldi]

I think the fp-ts docs are super important to have though, even if it's just there as a reference => for "as a reference" there is the reference doc I suppose.

I don't think they should be buried. fp-ts presents a ton of concepts that are super valuable on their own and I feel like they deserve a front and center explanation. => that's not Effect, you could use Effect without ever knowing about a typeclass and without caring about options, for the purpose of Effect the concepts that are front and centre in Cats/Haskell/Fp-TS/PureScript should be buried to the point of not return.

lots of people have benefited from fp-ts => lots is a very subjective term, in comparison to the number of TS users fp-ts had an impact on the 0.1%-0.5% (optimistic), by Giulio's words fp-ts had some degree of adoption because io-ts was a good trojan horse.

In short this library is not about making FP popular, it's about "exploiting" some of the FP patterns in ways that the average developer can adopt without background, for what I've seen so far it takes longer to the average fp-ts dev to approach Effect compared to one that never went deep on fp-ts, many of the concepts of fp-ts are plain wrong, for example the whole stack composition of Reader / ReaderTask / etc they are all based on the fact that "reader is a function" and "error is represented as left of either" (neither of which is true in a general sense, they both are implementation details of a specific design). In my world there are some good ideas and a lot to delete from fp-ts.

[jessekelly881]

Makes sense! I think your probably right.

[mikearnaldi]

updated content structure with a new section "Utility Modules" for modules such as "Either / Option / HashMap / etc"

[aniravi24]

Eventually if we have other top-level sections in the docs such as Guides (Tutorials), Ecosystem, etc., it might make sense to move all of the sections you proposed above under a section called "Learn" or something like that, so there's less crowding of options to select from when one initially opens the menu.

[OlaoluwaM]

I think it might be worthwhile to find other projects whose documentations we can draw inspiration from. For instance, the Tailwind docs are pretty good. Another might be the new React docs. The idea here is to learn and adapt what already works, y'know 😄.

[OlaoluwaM]

Here's a rough draft for a possible structure. Thoughts?

Get Started
├── Introduction
│   └── Ecosystem
├── What is Effect
└── Quick Start? (For those already familiar with fp-ts)
    └── Guide mapping fp-ts to effect and link to other tutorials
Core Concepts
├── .
├── ..
├── ...
└── ....
SubTopic-1
├── .
├── ..
└── ...
SubTopic-2
├── .
├── ..
└── ...
Tutorials/Examples/Recipes
Contributing
FAQ

[mikearnaldi]

Here's a rough draft for a possible structure. Thoughts?

Get Started
├── Introduction
│   └── Ecosystem
├── What is Effect
└── Quick Start? (For those already familiar with fp-ts)
    └── Guide mapping fp-ts to effect and link to other tutorials
Core Concepts
├── .
├── ..
├── ...
└── ....
SubTopic-1
├── .
├── ..
└── ...
SubTopic-2
├── .
├── ..
└── ...
Tutorials/Examples/Recipes
Contributing
FAQ

I wouldn't put fp-ts prominently, the docs mostly has to address people who don't know anything about fp

[mikearnaldi]

I think it might be worthwhile to find other projects whose documentations we can draw inspiration from. For instance, the Tailwind docs are pretty good. Another might be the new React docs. The idea here is to learn and adapt what already works, y'know 😄.

That's for sure something but the risk is drawing inspiration from something with a different surface, for example React / tailwind / etc are only talking about a single thing, in Effect we have modules that do completely different things and ecosystem packages so not sure where to look for that would be relevant

[IMax153]

I generally like the structure proposed by @OlaoluwaM. I think it provides a good start.

However, I agree with @mikearnaldi - I think we should avoid strongly associating Effect with "functional programming". Though Effect has its roots in FP, one of the design goals of Effect is to be usable by those without an FP background.

[OlaoluwaM]

That's for sure something but the risk is drawing inspiration from something with a different surface, for example React / tailwind / etc are only talking about a single thing, in Effect we have modules that do completely different things and ecosystem packages so not sure where to look for that would be relevant

I think then it might be reasonable to have the Effect-TS docs be just about Effect and the things that relate to it directly, core concepts, examples, etc.... Anything else should have it own docs. What do you think? This also has the added benefit of keeping the docs smaller overall, which, IMO, will make Effect seem like it's easy to get started with quickly

[err0r500]

Personally, I liked ZIO docs structure when I discovered it. Especially the fact they were oriented in a "problem solving" way : you want to achieve X -> you can do that with Y (based on examples which provide opinionated best practices). This is great to get started and when one's confident, reference doc alla fp-ts is nice.

[SandroMaglione]

Hi everyone,

I would propose some suggestions for the docs:

• Why not add the Introduction to Effect, Michael Arnaldi, WorkerConf 2022 Dornbirn video in the docs? I think it helps a lot to frame the problems that Effect aims to solve and the actual solution in code
• In the video Micheal suggests to create a common.ts file that exports each Effect module. I think also this can be added in the docs
• I think the Examples section plays an important role. The core of this section can contain some common usecases and how Effect helps to solve them, and then this can also be subdivided in "Official examples" and "Third party examples" (similar to Riverpod)
  • For example, we may add the Effect wrapper of fetch from Micheal's video as first example
• It may be worth adding each individual API reference as a sub-menu (Sub docs) in the nav bar

If this works I can open a PR to add the structure above, as well as some other examples of Effect code that I implemented.

[ethanniser]

Hi all, recently discovered Effect and have really fell in love. I know how important having good docs is for driving adoption and so I want to help contribute because there is a lot of work to do.

When looking for some kind of "plan" or "structure" for the docs I found this issue, which is kind of dead and never really went too far in the first place.

I know @gcanti has been working hard on the docs and it is awesome work, I don't know if he has his own 'structure' he is working off of, but I think it would be helpful for everyone to have a clear plan for what we want the docs to look like. This will make it easy for contributors to browse what is left to be completed, request and be assigned it.

I spent the last hour making a fresh "content structure".

To start I just want to emphasize I am still new to Effect and totally open to changes, discussion and feedback. The "plan" is by no means complete, there are many spots still to fill out and finalize. I just want to get the ball rolling.

Here were my goals when writing it:

1. Make the experience for new devs the absolute best it can be, a clear logical page -> page -> page that gets a new dev familiar with the concept of effect and the basics
2. Make it easy for intermediate Effect devs to find the more advanced tools to solve their problems
3. Merge the original structure from @mikearnaldi at the start of this issue (which I like the overall idea of) and the current state of the site (has some well written content on it)
4. Make the 'plan' as wide as possible and after completing it we can just focus on filling in the content we are able to, section by section

here it is

---

some final thoughts:

• trying to organize a library this big is really challenging, there is so much to cover and many different ways to introduce different topics/concepts
• I think the way pigoz/effect-crashcourse does the first 4 chapters is really really good and we should take inspiration
• I found this tweet very insightful, and I think it provides an interesting prospective for writing documentation. I think we should aim to get a new dev familiar with these “30-40” most common functions as quickly and as easily as we can.
• we should avoid making “dropdown” buttons ALSO pages, as its very confusing, especially when currently some (scheduling) are and others (the rest) are not

• the home/index page should have a massive "Get Started" button that takes you to the first page of the docs, right now its kind of confusing where to go and the button is very small

Writing docs is really hard (and really important), so I'm excited to contribute to help make Effect's docs the best we can

let me know what you think, thanks!

[adrian-gierakowski]

@ethanniser I believe the structure has been agreed but it was never mentioned here. See https://discord.com/channels/795981131316985866/1116789625017610312/1116822642499002470. The work has been progressing quite well with new content dropping daily.

[ethanniser]

I see

Really wish someone had updated or closed this issue, I think its unreasonable to expected people new to Effect to be aware of information in non-pinned discord messages from weeks ago. Maybe we can put the roadmap somewhere in the repo?

All good though, still happy to help if help is wanted

[gcanti]

Update:

We are following the guidelines provided by https://documentation.divio.com/.

The documentation is organized into six main sections to help you navigate and contribute effectively:

1) Concepts (aka Explanations in documentation.divio.com): In this section, you'll find detailed explanations and discussions about various concepts related to Effect. These resources aim to provide a deeper understanding of the underlying principles.

2) Effect Essentials: This section covers the fundamental components and core concepts of Effect. It serves as a starting point for beginners and provides essential information to get you up to speed.

3) Tutorials: The tutorials section is specifically designed for beginners. It offers step-by-step instructions and practical examples to help you learn Effect effectively. Follow these tutorials to gain hands-on experience and build a solid foundation.

4) How-to Guides: In the How-to Guides section, you'll find instructions on how to accomplish specific tasks using Effect. These guides are targeted towards users with some experience and provide detailed steps to achieve particular outcomes or solve common problems.

5) Reference Guides (this section is currently missing as we are still brainstorming on how to create it): The Reference Guides section contains technical descriptions and comprehensive references for Effect. This section is a valuable resource for in-depth exploration of the machinery, APIs, and features of Effect. It serves as a go-to reference for detailed information.

6) More: The More section includes miscellaneous resources that can't be categorized into the previous sections. Here, you'll find additional materials such as FAQ, Glossary, and other relevant information that complements the other sections of the documentation.

---

a clear logical page -> page -> page that gets a new dev familiar with the concept of effect and the basics

I completely agree, and I'm actively working on creating a golden path for our users. Essentially, the path for a user should be intuitive, starting from the top and progressing downward. As they move down the path, the resources become more in-depth and require greater knowledge, especially from the previous sections.

Based on what you wrote in the provided link:

Basics:

1) Concepts: This section is designed for new developers who are interested in understanding the principles of Effect. It introduces the fundamental concepts and explains the reasons behind using Effect. (TLDR It introduces the "what" and "why" of Effect)

2) Effect Essentials: This section is tailored for new developers who want to learn about the practical aspects of Effect. It covers the essential core functionalities. It is recommended to read this section in its entirety, in the specified order. (TLDR It covers the super “core” stuff)

Building Your Application:

3) Tutorials: This section provides step-by-step instructions for performing specific tasks. It serves as a guide for beginners to start building their applications with Effect. While readers can explore different tutorials based on their needs, it is still advisable to read all the tutorials in sequence to grasp a comprehensive understanding. (TLDR the (beginner) reader can start branching out)

4) How-to Guides: Similar to tutorials, guides offer instructions for accomplishing specific tasks. However, these guides are intended for users with more experience in Effect. They address more advanced scenarios and introduce additional advanced components of Effect that can help solve sophisticated problems. (TLDR like one-off “articles” related to Effect but can introduce new code)

[mikearnaldi]

I see

Really wish someone had updated or closed this issue, I think its unreasonable to expected people new to Effect to be aware of information in non-pinned discord messages from weeks ago. Maybe we can put the roadmap somewhere in the repo?

All good though, still happy to help if help is wanted

That's my fault sorry about that, in order to unlock the first good draft of docs we've elected Giulio as the driver for this and it should have been mentioned in the issue.

Contribution is welcome and if you're willing to help the effort please coordinate with Giulio on where to start, having a beginner mindset when writing docs is very important so I see the fact that you're just getting into Effect as a plus.

[gcanti]

I found this tweet very insightful, and I think it provides an interesting prospective for writing documentation. I think we should aim to get a new dev familiar with these “30-40” most common functions as quickly and as easily as we can.

Yup, ideally these “30-40” most common functions should be covered by Effect Essentials + Tutorials

we should avoid making “dropdown” buttons ALSO pages

I agree, the only exception was (https://github.com/Effect-TS/website/pull/93) scheduling

the home/index page should have a massive button

:+1: https://github.com/Effect-TS/website/pull/94

(Note: we will work on a "real" landing page asap)

@ethanniser thanks for your suggestions

[ethanniser]

@gcanti this all sounds good, woke up this morning and watched the divio talk and its very well thought out.

Having well defined "categories" is great, although I still think it would be beneficial to have an actually written out plan for what actual pages we want to have in each of the sections. Maybe this already exists, but I can't find it.

---

With me being new to Effect I think I can contribute the most providing feedback/changes to existing pages with the "beginner mindset" instead of writing new content (I'll leave that to you as you know what your doing)

Some ideas I have right now if any of them sound good to you, happy to work on them if so:

• Add a "building errors" section of "Error Management" that will look similar to pigoz/effect-crashcourse, right now its barely even mentioned
• Adjusting some of the titles/phrasing in "Using Generators", while I think it makes a lot of sense once you understand whats going on, if you've never see it before I think its a bit overwhelming
• I would also be interested in your thoughts on moving the "Do Simulation" page to the bottom of the "Generators" page as they follow very similar ideas
• adding explicit type annotations to many of the example code blocks, while many of the examples mention the type in the text before or after, having it in the code adds clarity. Although I do understand the concern for not wanting new devs to think that this is necessary for real code
• Rewriting "Data-First and Data-Last", I understand what this section is trying to do but I found it very confusing first read
• Clear comparison between map and flatMap. I found this difficult given how that page is currently written, both sections are nearly identical expect for a couple lines, and then they are separated by the "Data-First and Data-Last" so its even harder to compare
• introducing Either and Option earlier rather than later and how they interact with effects

again from pigoz/effect-crashcourse:

/ NOTE about Effect.flatMap(eitherFromRandom)

• Through some black magic, Either and Option are defined as sub types of the
• Effect type. That means every function in the Effect module can also accept
• Either or Option and tread them accordingly.
• Effect.flatMap(() => Either.right(1)) will turn into an Effect.succeed(1)
• Effect.flatMap(() => Either.left(2)) will turn into an Effect.fail(2) */

/* Up to this point we only constructed Effect values, none of the computations

• that we defined have been executed. Effects are just objects that
• wrap your computations as they are, for example pipe(a, flatMap(f)) is
• represented as new FlatMap(a, f).
• This allows us to modify computations until we are happy with what they
• do (using map, flatMap, etc), and then execute them.
• Think of it as defining a workflow, and then running it only when you are ready. */

/* As an alternative, instead of using eitherFromRandom and dealing with an

• Either that we later lift into an Effect, we can write that conditional
• Effect directly.
• Both are valid alternatives and the choice on which to use comes down to
• preference.
• By using Option/Either and lifting to Effect only when necessary you can
• keep large portions of code side effect free, stricly syncronous, and not
• require the Effect runtime to run.
• Using Effect directly you lose some purity but gain in convenience.
• It may be warranted if you are using the dependency injection features a
• lot (especially in non library code). */

I think this is an interesting topic that I didn't know about after reading just the effect docs. Maybe you guys don't agree and would prefer to keep code as Effects all the way down? Just something to think about

[gcanti]

@ethanniser great feedback, thank you. I agree with many points, but I would keep this issue focused on guidelines, the overall structure of the website, and (maybe) general matters that apply to all sections. I suggest moving the discussion on specific points to dedicated issues, one for each major topic (e.g., one for "Effect Essentials," one for "Error Management," etc.), so that they are neither too broad nor too granular with an excessive number of issues.

[ethanniser]

will make dedicated issues for the other stuff

---

as for this issue:

Having well defined "categories" is great, although I still think it would be beneficial to have an actually written out plan for what actual pages we want to have in each of the sections. Maybe this already exists, but I can't find it.

still think this is important to do, if you agree @gcanti

[ethanniser]

just want to bump this

I think planning out all the pages we eventually want to have and adding them as "stubs" would make the docs feel much more "complete" for no real work, as well as increasing the chance someone sees a stub for something they want to learn about and decides to help contribute to that section

[gcanti]

Yes, that's how we intend to proceed. We have envisioned a first series of pages and have added them as stubs (for example, https://www.effect.website/docs/concepts/immutability), and now we are filling them with content. Once this initial phase is completed, which also serves to refine the process and make many small decisions (such as what type of examples to include, how to indicate warnings, errors, etc.), we will have a new brainstorming session to start a new cycle of stubs + contents. The first cycle, which is currently underway, will take a bit longer because it's the first one and we need to test it concretely. However, if you already have some proposals for stubs for the second cycle, feel free to share them here.

[ethanniser]

Thank you for this response, this sounds like a good plan. Could we also add this to the readme @gcanti? I would consider this really important information for anyone wanting to contribute to the project that isn't mentioned anywhere in the repo. After looking back through the #docs channel in the discord today I found this message from @mikearnaldi

Giulio is working on a first version together with Johannes. The reason I paused uncoordinated effort is primarily because we were losing the direction too easily, with a focus group it's easier to maintain a coherent line. As soon as the first version is out we will have a great basis to contribute into

Totally understand this and I agree with the rationale, but as I mentioned earlier its just not reasonable to expect new contributors to be aware of information in non-pinned discord messages from weeks ago.

My actions as a contributor would've been very different having known this information, so I hope we can keep these important directional decisions reflected in the readme or a contributing guide going foward.

I look forward to contributing more once the 'first version' is complete

[gcanti]

I hope we can keep these important directional decisions reflected in the readme or a contributing guide going foward

@ethanniser 👍 I have added a "Contributing" section to the README. Honestly, the work on the documentation has just started after a period of calm, and we were caught off guard. We didn't expect such quick participation (I mean, pleasantly surprised). Thank you for the feedback you have provided so far, it's highly valuable to us.

[IMax153]

Closing this discussion as the content structure has been relatively stable until the recent website rebuild.