Welcome, Guest | Browse

Software Factory Archive

← Previous Work All Works Next Work →

The Documentation Philosophy

Rating:
General Audiences
Fandom:
StrongDM Software Factory
Characters:
Jay Taylor Navan Chauhan Justin McCarthy
Tags:
Character Study Documentation HTML Accessibility PDFs
Words:
492
Published:
2026-01-06

Jay's position on documentation was simple, uncompromising, and occasionally annoying to people who didn't share it: all documentation should be accessible HTML. Not PDFs. Not Google Docs. Not Confluence pages trapped behind authentication. HTML. The language of the open web. The format that every browser on every device could render without additional software, without accounts, without permission.

He'd held this position for years. Before the factory, before StrongDM, he'd once taken an entire software manual—three hundred pages of installation guides, API references, and troubleshooting steps, all locked inside a PDF that required a specific viewer version to render correctly—and converted it to a static HTML site. He did it on a weekend. He published it on a personal server. He sent the link to the original authors with a note that said, "I made your documentation accessible. I hope that's okay."

It was okay. More than okay. The HTML version got ten times the traffic of the PDF within a month, because search engines could index it, because screen readers could parse it, because people on slow connections could load one page at a time instead of downloading a forty-megabyte monolith.

"PDFs are cages," Jay told Navan during a conversation about the factory's documentation strategy. "They trap content inside a format that's designed for printing, not for reading. You can't link to a specific section. You can't search across documents. You can't resize the text without breaking the layout. You can't copy code examples without losing the formatting."

"I like PDFs," Navan said, because he did. His academic papers were in PDF. His university lecture notes were in PDF. PDF was the format of his educational history.

"PDFs are fine for archival purposes," Jay conceded. "For a fixed document that needs to look exactly the same on every device, a PDF makes sense. But documentation isn't archival. Documentation is alive. It changes. It gets updated. People need to find specific paragraphs and link to them and share them. HTML does all of that. PDF does none of it."

The factory's documentation reflected Jay's philosophy completely. Every spec, every scenario description, every architecture decision record was in HTML or Markdown that could be rendered as HTML. The agents could read it. The search tools could index it. The web could serve it. No viewer required. No account needed. No format lock-in.

Justin supported this not because he cared about the format war between HTML and PDF, but because he cared about what Jay cared about underneath it: accessibility. Not accessibility in the narrow sense of screen readers and ARIA labels, though Jay cared about those too. Accessibility in the broader sense of making knowledge available to anyone who wanted it, without barriers, without friction, without the assumption that the reader had the same software, the same permissions, the same context as the writer.

"Documentation should be as accessible as the knowledge it contains," Jay said once. He said it simply, without emphasis, as if it were self-evident. Navan wrote it in his notebook anyway, because self-evident things are the ones most worth recording. They're the ones people forget to say out loud.

Kudos: 73

html_evangelist 2026-01-08

Converting a three-hundred-page PDF to a static HTML site on a weekend and then politely telling the authors he'd made their documentation accessible. That's not passive aggression. That's active generosity. Jay is the patron saint of the open web.

pdf_defender 2026-01-09

I came in ready to fight the anti-PDF take and then the fic had Jay acknowledge PDFs are fine for archival purposes. Fair. Balanced. Still wrong about most things, but fair. The accessibility argument is hard to argue against.

← Previous Work All Works Next Work →