diff --git a/ratatui-elm/src/lib.rs b/ratatui-elm/src/lib.rs
index 1a3d536..14b6f44 100644
--- a/ratatui-elm/src/lib.rs
+++ b/ratatui-elm/src/lib.rs
@@ -1,7 +1,30 @@
-//! This library implements an Elm-like framework based on Ratatui
-//! That will allow the users to build TUI applications by just providing
-//! an Update function, a View function, a terminal and a model.
+//! Elm-like framework based on Ratatui.
 //!
+//! The state of your application is represented by a single type called the Model.
+//!
+//! The Model will be used by a `view` process to render a View.
+//!
+//! A separate process will read events from the outside world and
+//! send them to an `update` process.
+//!
+//! The `update` process will take the model and an event and
+//! return a new model, potentially also returning a side effect.
+//!
+//! The updated model will be sent to the `view`, triggering a new render
+//! based on the new state of the application.
+//!
+//! If any side effects are returned from `update`, they will be processed
+//! in a separate process.
+//!
+//! If the process responsible for handling side effects wants to update
+//! the state of the application, it will send a message to the `update` process.
+//!
+//! The users of this framework only need to provide:
+//!
+//! - An update function that given a model and a message return an `Update` instance.
+//! - A view function that given a reference to the model, returns a `View`
+//! - An effects function that given a reference to the model and an effect,
+//!   might perform any side effects and optionally return a message to update the state of the application
 use color_eyre::Report;
 use color_eyre::Result;
 use std::{
diff --git a/ratatui-elm/src/update.rs b/ratatui-elm/src/update.rs
index 848ea1c..5b6381c 100644
--- a/ratatui-elm/src/update.rs
+++ b/ratatui-elm/src/update.rs
@@ -1,5 +1,4 @@
 //! Actor responsible of maintaining the state of the application.
-//! Other actors can query the state of the model or send updates.
 use color_eyre::{Report, Result};
 use std::sync::mpsc::{Receiver, Sender};