โ€ข

newsletter

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

How to learn a new library when the official documentation is not enough: use the API reference, explore and search the open source repository, read tests, ask for help from the community.


Sandro Maglione

Sandro Maglione

Software development

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 readThis 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 testsSearch "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 examplesClick 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 examplesSearch 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 helpAsk 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:

This means that more will come, I will continue sharing my journey as I learn more and more ๐Ÿ”œ

See you next ๐Ÿ‘‹

Start here.

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