diff --git a/README.md b/README.md
index 8360ff9e..3a5bdbaf 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 # Thermodynamics.jl
-A package containing a library of moist thermodynamic relations
+
+Thermodynamics.jl provides flexible and performant functions for computing various thermodynamic variables for dry and moist atmospheres.
 
 |||
 |---------------------:|:----------------------------------------------|
@@ -20,3 +21,4 @@ A package containing a library of moist thermodynamic relations
 [codecov-img]: https://codecov.io/gh/CliMA/Thermodynamics.jl/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/CliMA/Thermodynamics.jl
 
+See our documentation [here](https://clima.github.io/Thermodynamics.jl/dev/index).
diff --git a/docs/src/index.md b/docs/src/index.md
index daefa0e8..4f587772 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,4 +1,31 @@
-# How to guide
+# Thermodynamics
+
+## Principal design
+
+This package uses an abstraction that leverages the idea of a thermodynamic state:
+
+ - given two (or more) independent intrinsic thermodynamic properties, we can establish a thermodynamic state and
+ - given a thermodynamic state, we can compute any thermodynamic property
+
+ 
+## Simple example
+
+For our example, we first load packages, and create a set of thermodynamic parameters, using a convenience constructor, offered through [ClimaParams.jl](https://github.com/CliMA/ClimaParams.jl). Then we create a thermodynamic state using density, liquid-ice potential temperature, and total specific humidity. Finally, we compute air temperature from the thermodynamic state.
+
+```@example
+using ClimaParams # needed in environment to load convenience parameter struct wrappers
+import Thermodynamics as TD
+params = TD.Parameters.ThermodynamicsParameters(Float64);
+
+ts = TD.PhaseEquil_ρθq(params, 1.0, 374.0, 0.01);
+T = TD.air_temperature(params, ts)
+```
+
+And that's it. See a full list of different thermodynamic state constructors, in case you want to create a thermodynamic state with different variables, [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-State-Constructors).
+
+See a full list of quantities that you can compute from a thermodynamic state, see our thermodynamic state-compatible methods [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-state-methods).
+
+## How to guide
 
 Thermodynamics.jl provides all thermodynamic functions needed for the
 atmosphere and functions shared across model components. The functions are