The manual is part of the product

Caffenol has a somewhat unique approach to UX. It’s inspired by roguelike games like Returnal or Hades: they feel impossibly challenging on your first run, but fun enough to try again. And again. Caffenol is a darkroom process roguelike.

The comparison doesn’t quite map 1:1 to making photos, but the goal is to make failing fun, mistakes legal, and recovery fast. And try again until you make cool art. Every control and timing impacts the final output, and it intentionally encourages experimentation over fast results.

Caffenol has many controls, and many are actually proxies for pretty complex algorithms or character profiles. Film stocks, for example, are a simple representation of film character like grain or halation. It started with black and white film emulations, quickly growing to color and slide. Each has a different way of developing, and creates new possibilities, controls, and failure modes. Introducing color printing processes started to push the complexity even further.

A developed print in Caffenol’s enlarger

Caffenol is an opinionated experience. I want Caffenol to reward effort with as little guidance on how to get results as possible. This creates tension: it should be easy to create good art while really rewarding experimentation and breaking things. It also needs to never feel hard to use, or that you need to know how a darkroom works to make something objectively good. I’m still learning the balance and making tweaks, but it became clear that documentation was needed either way.

Why a (user) manual

I love good documentation, and photography companies have some incredible user manuals, like the excellent Rolleiflex 2,8GX User’s Manual or vintage Broncolor. Caffenol’s manual landed shortly after I found those, with the explicit goal of helping power users level up their understanding of the process and leverage the way it works to make interesting results.

A page from the Rolleiflex 2,8GX User’s Manual.

Aside from the design & aesthetic of product manuals, I find them immensely helpful for understanding opinionated or complex functions or workflows. Software can overrotate towards simplicity and intuitiveness, and documentation might be a signal that the product is actually not easy to use. But complexity exists on a spectrum: on one hand, paying a power bill shouldn’t need any documentation. For Neovim, the documentation might be required reading to get started. Caffenol sits in the middle.

The interface carries the first 80%: good affordance with clear controls, skeuomorphic elements, and tight retry loops. The manual is progressive disclosure for the last 20%, the power users who want to understand the internals. And break them.

But a manual for software has a problem a Rolleiflex manual never had: the product keeps evolving.

Keeping it updated

Manuals for physical products are stable and static. Revisions definitely ship in the world of print, but for the most part, content and structure stays the same. That’s not the case for digital products, especially when new controls, changes to existing tuning, or other workflow tweaks ship. Text is cheap to change, but in a user manual, diagrams and photos make the documentation more scannable and intuitive.

I’ve always struggled with keeping screenshots or videos up-to-date in documentation. As things change, I really don’t want to manually capture adjustments or run a script. The trick: the manual’s screenshots are vitest visual regression snapshots, generated in CI.

When a component changes, its snapshot is re-rendered and the manual page picks it up automatically. Every visual in the manual has an anchor in code, so it’s future-proof — the screenshots can’t go stale. It doesn’t quite work for animations or video (yet).

Automation keeps the screenshots accurate, but it doesn’t make the pages feel like a manual worth reading.

A manual style that looks like a Caffenol export

Caffenol is built on randomness. Every run looks different. The manual is no exception, and Caffenol’s paper simulations render on the manual page. Old manual scans have unique artifacts: creases, noise, scan errors, coffee marks, and handwritten notes. These reflect the lived history of an object, and this chaos is at the core of Caffenol’s design philosophy.

The manual’s cover renders on Caffenol’s simulated paper

It’s also massively inspired by a friend: Ky Decker and their work on Namesake.fyi, which combines texture with extended colors to create something unique.

Somewhere along the way, the manual became less of an afterthought and more integrated into how new things are built and imagined.

Writing the docs before the feature

New features now start as a write-up in the manual, almost like a PRD. Writing user-facing docs forces you to hold two positions: your own opinion of how it should work, and how someone reading it might guess how it actually does.

Caffenol began by only supporting black and white workflows. Developing and printing black and white in the real world is far simpler than color negative or slide. The product needs to support color without the complexity of its real-world process. The first pass for this actually started in the manual as a 1:1 replication of the color workflow. In writing the docs, I realized fairly quickly it would be accurate to the real world but not fun at all. So, the docs changed to a different process that departs from the real world and gives users visual feedback in real time.

The Color and Slide section came to life before the functionality did.

Most importantly: the manual is both an artifact of the product and part of how it gets made.