diff --git a/docs/references/observability.rst b/docs/references/observability.rst
index 687e6ac78..de75c5d79 100644
--- a/docs/references/observability.rst
+++ b/docs/references/observability.rst
@@ -3,6 +3,8 @@
 Observability
 #############
 
+Observability allows measuring a system's current state based on the data it generates, such as logs, metrics, and traces.
+
 .. contents::
    :depth: 1
    :local:
diff --git a/src/PostgREST/Logger.hs b/src/PostgREST/Logger.hs
index 812618926..08ad5b166 100644
--- a/src/PostgREST/Logger.hs
+++ b/src/PostgREST/Logger.hs
@@ -1,7 +1,8 @@
 {-|
 Module      : PostgREST.Logger
-Description : Wai Middleware to log requests to stdout.
+Description : Logging based on the Observation.hs module. Access logs get sent to stdout and server diagnostic get sent to stderr.
 -}
+-- TODO log with buffering enabled to not lose throughput on logging levels higher than LogError
 module PostgREST.Logger
   ( middleware
   , observationLogger
@@ -54,6 +55,7 @@ logWithDebounce loggerState action = do
       putMVar (stateLogDebouncePoolTimeout loggerState) newDebouncer
       newDebouncer
 
+-- TODO stop using this middleware to reuse the same "observer" pattern for all our logs
 middleware :: LogLevel -> (Wai.Request -> Maybe BS.ByteString) -> Wai.Middleware
 middleware logLevel getAuthRole = case logLevel of
   LogCrit  -> requestLogger (const False)
diff --git a/src/PostgREST/Observation.hs b/src/PostgREST/Observation.hs
index 2dfd94b22..28cdbf3ef 100644
--- a/src/PostgREST/Observation.hs
+++ b/src/PostgREST/Observation.hs
@@ -1,7 +1,7 @@
 {-# LANGUAGE LambdaCase #-}
 {-|
 Module      : PostgREST.Observation
-Description : Module for observability types
+Description : Observations that can be used for Logging and Metrics
 -}
 module PostgREST.Observation
   ( Observation(..)