Livebook is a secret weapon for documentation

Summary

The post presents Livebook as an interactive way to document the central logic of an Elixir or Phoenix application, helping new developers understand and explore code alongside existing documentation and tests. Using a TicTac example, it documents and executes the GameState module and struct, then describes and demonstrates a Horde-managed GenServer that runs the game state. Livebook connects to an existing project through a Mix standalone runtime, providing Elixir code completion, Markdown explanations, execution, and access to operations such as Ecto queries, context calls, and starting GenServers. The resulting notebooks are plain Markdown files, can be stored in source control, and support experimentation, reviewable diffs, and collaborative editing. The setup described requires Elixir 1.12: install Livebook with mix escript.install hex livebook, start livebook server, and connect through the locally generated token URL.

Takeaways

1. 1

   Livebook can load an existing Elixir project and combine Markdown explanations with executable Elixir code, allowing documentation to show results interactively.

2. 2

   Notebook files use plain Markdown, so they can be checked into source control and diffed and merged as part of the project.

3. 3

   A connected Livebook runtime can execute Ecto queries, call contexts, start GenServers, and demonstrate application logic such as the GameState module and its Horde-managed server.