Three lessons from a year of shipping document converters nobody warned me about
I've been running a family of document-to-Markdown converters for over a year now — PDF, DOCX, PPTX, XLSX, EPUB, HTML, plus a universal endpoint that auto-detects the lot. Most of the engineering lessons came from failures in production, not from documentation. Lesson 1: The input is never what the spec says. My PDF parser handled every test file I threw at it. Then a user uploaded a scanned contract with a rotated text layer and it silently returned an empty document. Silent failure is the worst failure mode for a converter — downstream, an empty string looks like success. I now return explicit warnings on low-confidence extractions, and I treat "zero content extracted" as an error, not a result. Lesson 2: Idempotency matters more than throughput. Agents love retrying. Without stable behavior on replays, the same document converted twice produced slightly different Markdown because of non-deterministic table detection. I keyed caching on content hash, not URL, so re...