How I learn a new library (when documentation is not enough)

My goal was to learn more about Effect, in the details: all methods, no matter how advanced, how to use them and why.

Documentation is not enough. How can I do without it? 🤷🏼‍♂️

This is how I go about learning a library, when documentation is not enough 👇

Tech stack

Effect: when a project is open source you can literally view and search all the code 🎉
Github: you'll be surprised how helpful Github can be when searching and reading code, it's your best friend 🤝
vitest: I write unit tests for myself when learning, this helps making sure that an API works as I expect

Setup

Welcome to 2024 👋

The tools for the web are so great nowadays. You have countless of options to setup a project, especially when the goal is to learn by yourself:

Cloud: StackBlitz, CodeSandbox, Github Codespaces
Local: Vite, ts-node,
Github

I opted for my local setup with typescript + ts-node.

Get started

First step: collect all the available documentation and resources.

This is the foundation. I keep these 3 tabs always open as I write code.

These form the core reference for my exploration.

There is more 🤩

Timeless coding principles, practices, and tools that make a difference, regardless of your language or framework, delivered in your inbox every week.

Implementation

Exploration is unconstrained. I literally opened the API reference and clicked on the first module that caught my attention.

For example, I happened to be working with Base64 the day before, so I searched for it in the API 💁🏼‍♂️

Turns out Effect has an Encoding module that implements Base64 encode and decode.

Now, the official documentation doesn't have a chapter about "Base64". The API reference in this case was enough:

This was easy since the signature is straightforward and simple to read

I wrote a test to make sure it works as I expected:

describe("Base64", () => {
  describe("decode", () => {
    it("should decode from Base64 to string", () => {
      const result = Base64.Base64Service.pipe(
        Effect.flatMap((base64) => base64.decode("Zm9vYmFy")),
        Effect.provide(Base64.Base64ServiceLive),
        Effect.runSync
      );
      expect(result).toBe("foobar");
    });
  });
});

Advanced API

Next stop was Context and Tag.

I used these modules in the past, but I had no idea how they worked internally.

The documentation usually focuses on concrete usecases, and not on implementation details 💁🏼‍♂️

Nonetheless, the best way to learn a technology is to understand the why and how from the internal implementation details

This is where Github and open source shine ✨

Search "Context" on the repository on Github. You will find all the information that you need. Specifically, the internal implementation and the tests

Github then helps you explore the code by giving references to all methods:

Click on any reference in the code and you will get links to sources and examples

Don't forget about tests! Every method is tested. This means that you will find for sure at least 1 example of how to use any API in the test file:

Search and open the test file and look for the API that interests you. You will find for sure 1 or more examples

Community support

Effect also has an awesome community over on Discord.

When I got stuck on some detail I sent a message to ask for help. Everyone is super friendly and willing to help, not matter how trivial is your question (thanks everyone 🙏🏼):

Ask for support from the community on Discord. Everyone is willing to help

I wrote down all my notes on the README of the open source repository, where you can read all the details of my exploration with links to all the APIs

Contribute back

The last step is always to contribute and share my learnings!

I wrote a complete getting started guide to Effect.

This is the guide I would give myself when I started learning about Effect 🔥

Takeaways

You can learn about any technology, no matter how complex
Open source is awesome: you can read and search the internal implementation of your favorite libraries
If the official documentation is not enough you can look at the API or at the internal documentation
Tests are your best friend: you can always find at least 1 example of any API
The Effect community is awesome: you should join

At the end I was able to explore only a very small set of modules. Effect has indeed a lot to offer: