ryanzidago

ryanzidago

After writing about the importance of executable evidence and explaining how I’m using doctests to document known limitations and moduledoc to specify high level product processes, I’m now writing another article about documentation.

I often find myself asking LLMs to explain me a complex feature. As a result, they may return quite some verbose text which isn’t pleasant to read all day long and takes me time to parse. I find code easier to reason about than English in some cases anyway.

Sometimes, I even ask them to back their statements with evidence, such as tests, which helps them correct their false assumptions.

At some point, I realised that I was using docs and tests separately, i.e. as a weaker version of doctests!

I could actually just let the AI agent explain me the feature through a high level overview as a moduledoc that is roughly of the following shape:

## Section title
What (observable product behaviour)
Why (product behaviour rationale)
<concrete illustrative example with doctests>
...

The more I work with LLMs, the more I love doctests.
They make the specification much easier to verify.
You can reduce drift if you keep the doc part thin and focused on the why.

Such a powerful feature for both humans and agents alike!

Where Next? Top

Trending in Blog Posts Top

bartblast
My first real blog post is up! Got five minutes? Come break some stuff. I put five demos in it, and they’re meant to be played with. Kill...
New
T0ha666
I run a kanban of AI coding agents, and one afternoon the board showed three tasks running while the profile page on the same screen said...
New
danschultzer
I wrote a post on how to implement a feature flag system and A/B testing in an Elixir app with no need for third-party services or librar...
New
videsnelson
Following up on Making `dns_erlang` fast: binary tricks for the BEAM, there’s our second post in our series on making erldns, an authorit...
New
danschultzer
A small quality-of-life improvement to my blog that makes it easier to keep technical posts up to date with a revision history. https://...
New
danschultzer
Wrote a post about how I set up HTML email templates in Phoenix using the template renderer with Gettext and verified routes, CSS inlinin...
New

Other Trending Topics Top

dominicletz
Hey there, I haven’t seen a list of useful Elixir specific skills for the popular AI tools yet so I’m starting one here with my first. ...
New
raa-ziq
Hi everyone :waving_hand: I wanted to share something I’ve been building — NowBlind, a random chat app designed to help people discover ...
New
mudasobwa
I fully migrated to my own harness from Anthropic/Gemini and I think it’s time to share it. Welcome DSH, the DeepSeek Harness, fully writ...
New
OndrejValenta
(I just needed to vent somewhere and LinkedIn is full of hope, or hype, I’m not sure which exactly) AI dream has many faces, but general...
New
kip
Localize is the next generation localisation library for Elixir. Think of it as ex_cldr version 3.0. The first version will be released ...
New
jimsynz
Beam Bots (or just BB for short) is a framework for building fault-tolerant robotics applications in Elixir using familiar OTP patterns. ...
New

We're in Beta

About us Mission Statement

Options

Thread Display Mode




Thread Preview

Skip Thread Previews