Parkside Labs

Software Is Different When the Output Arrives in the Mail

You can't hotfix a printed book. Building software that ends in a physical object changed how we think about bugs, QA, and what done means.

For most of my career, software ended at a screen. Someone clicked a button, data moved through a system, the page updated. When we got something wrong, we read the logs, shipped a fix, and every user had the correction within the hour. The product stayed fluid forever. That property is so fundamental to web development that I never thought of it as a property. It was just what software was.

Then we started building Genie in a Book and Genie Comics, where the output of the software is a hardcover book that gets manufactured, boxed, and mailed to someone's house, usually for a birthday. The code still collects information, calls APIs, and coordinates workflows, same as always. But the last step turns bits into an object, and the object doesn't take patches.

There's no hotfix for a sealed box

In web work, deployment is where things become real, and fixing forward is a legitimate strategy because a patch reaches everyone instantly. Once a book enters production, that whole mental model stops applying. Files go to the print provider, pages get imposed for manufacturing, covers and interiors run separately, the book is bound and handed to a carrier. By the time a customer sees the problem, our software might have been fixed for a week. Their copy is still wrong.

That forced us to find the exact point in our workflow where a cheap digital mistake becomes an expensive physical one. For us it's the moment an approved book becomes a submitted print order. Everything before that line can move fast and get corrected freely. The line itself deserves the kind of scrutiny you'd give a manufacturing release, because that's what it is. This isn't an argument for moving slowly everywhere. It's an argument for knowing where your one-way door is and putting your strongest checks in front of it.

Bugs acquired a material cost

A bug caught during review costs a regeneration and a few minutes. The same bug caught after printing costs the ruined book, a replacement run, upgraded shipping to make up lost time, a support conversation, and sometimes the thing money can't fix, which is the birthday it missed.

Severity also came unglued from code size. A one-line layout error can put text inside the trim edge and make an entire print file unusable. A page-ordering mistake turns a coherent story into nonsense. A mismatch between the cover spec and the generated file can stall production even though every API call returned 200. So we stopped asking only how likely a bug is and started asking when we'd catch it. A frequent bug that's obvious on screen is an annoyance. A rare one that only shows up on paper is a budget item.

The product is a chain, and every link can pass while the chain fails

A finished book is the end of a long series of transformations: photos identified, roles assigned, story generated within the product's constraints, illustrations matched to scenes, pages assembled, print files rendered, printer requirements satisfied, order submitted with the right options, then manufacturing and delivery. Each step can succeed by its own definition while the end result fails. The story text is valid but too long for its page. The illustration is lovely but puts the kid's face in the gutter. The PDF parses perfectly and contains the wrong image.

Eleven systems reporting success means nothing to a customer holding a bad book from the twelfth. Unit tests and service checks are still worth having, but they can't prove the final object is right, so most of our validation effort goes into inspecting the assembled result rather than the individual steps.

A valid file can still be the wrong file

Related lesson, worth its own heading because it changed how we automate. Automated checks are excellent at questions with measurable answers: page size, page count, embedded fonts, missing assets, render completed. They're nearly useless for the questions customers actually care about. Does this still look like their daughter? Does the emotional beat land? Does the comic page read in the right order? Is the title sitting on the spine like someone meant it to?

We automate everything in the first category aggressively and keep humans, including the customer, on the second. The boundary moves as tools improve, but pretending the second category doesn't exist is how you ship a technically flawless disappointment.

Print specs became software requirements

Trim, bleed, safe area, gutter, spine width, color profile. Before this business I'd have called those printing details, somebody else's vocabulary. They turned out to be requirements that reach all the way back into our data model and layout engine. Art has to extend past the trim line so a millimeter of manufacturing variance doesn't leave a white sliver. Faces and text have to stay inside safe boundaries. Spine width depends on page count and paper stock, which means the cover can't be finalized until the interior is. Comics add their own: a panel border that looks fine on a monitor feels cramped after trimming, and lettering that's readable at full screen can be miserable at print size.

The two formats even fail differently. A storybook page has room to absorb a small compositional flaw. A comic page is dense, and one drifting speech balloon can cover the art that mattered. Shared infrastructure did not buy us shared quality rules, which we learned by testing actual formats instead of assuming.

The customer became part of QA

Our customers know things our software cannot know. Whether the child is recognizable. Whether grandpa looks like grandpa. Whether the detail the system treated as background was actually the point of the whole book. So we put customer review and approval before the print submission, where corrections are still cheap.

Designing that step was its own product problem. The review has to be understandable to someone who's never heard the word "proof," has to make clear what can and can't change, and has to prevent accidental approval without becoming a maze. There's a balance between giving customers real authority over the result and making them do unpaid work as an art director. But the principle held up: the person with the missing context should see the book before the printer does.

Some questions only paper can answer

Ordering physical proofs of your own product feels painfully slow to a software team. There's no instant feedback; you submit a file and wait for a box. We do it anyway, because monitors lie. Colors shift on paper, dark images swallow their detail, text reads smaller than it did on screen, and a cover that's balanced as a flat rectangle feels different wrapped around an actual spine. Paper stock alone decides whether the book feels like a keepsake or a catalog.

Samples also taught us to treat the printer as part of the architecture rather than a fulfillment box on a diagram. Their catalog constrains our formats, their file specs shape our rendering, their production times shape our promises. Software instinct says vendors are swappable implementations behind an interface. Physical vendors are not. Switching printers is less like changing an API provider and more like changing the product.

Traceability is a support tool now

Observability ends at the handoff. We know a file was generated, validated, submitted, and marked shipped. We don't see the object move through manufacturing, and we usually only see the finished copy if a customer photographs it. So everything before the handoff has to leave a paper trail: which story version, which image generations, which rendering logic, which product configuration, exactly what was sent. When someone reports a problem with a physical book, support has to reconstruct the digital history of that specific object, down to confirming that the approved version of a regenerated image is the one that made it into the file. Versioning stopped being a development convenience and became how we answer customer emails.

One more thing the calendar taught us: severity has a date attached. A minor defect on an ordinary Tuesday is minor. The same defect nine days before a birthday is critical, because the production window is closing and there's no second chance at the occasion. We prioritize with the event date in view, and we quote timelines honestly even when the optimistic number would convert better. An honest timeline is part of the product; an optimistic one is a complaint scheduled in advance.

Done means the right thing arrived

Software teams define done as merged, tested, deployed. Our definition had to grow. The customer's book still has to survive generation, approval, payment, manufacturing, and a delivery truck, and from their side the product is done when they open the box and it's right. That doesn't make us responsible for the weather, but it does mean the product design has to cover communication, recovery, and support for all the parts we don't control.

Watching code turn into an object a family keeps on a shelf has been the best part of this company. It's also the thing that made one lesson permanent: the product isn't finished when the software says it's finished. It's finished when the right thing arrives.