The situation
The MadCap Flare stylesheet powering all customer-facing documentation had grown to nearly 2,800 lines over two years and three contributors — two developers, a vendor template, and my own incremental updates along the way. Every change added styles. Nothing was ever removed.
It worked. But just barely.
With three output types sharing a single stylesheet — PDF, HTML5 web, and mobile — organizational debt was starting to cause real problems. Print-from-web was triggering unnecessary page breaks and shifting layout divs because PDF-specific rules were bleeding into the web output. Styles accumulated from past writers sat unused, making it genuinely difficult to know which rules were active and which were ghosts. Onboarding a new writer would have meant a lengthy explanation of what to ignore.
The bigger issue was strategic. The launch of Academy 2.0 — our new documentation portal — raised the bar for what "good" looked like. Content and platform needed to feel like they came from the same place. They didn't.
What I set out to solve
The goals weren't just cosmetic:
- Readability and accessibility across all three output types, with particular focus on mobile — an increasingly common access point for field technicians
- Output separation — PDF rules and web rules needed to stop interfering with each other
- Visual consistency between the documentation and the Academy portal
- Maintainability — a stylesheet the next person could actually navigate
What I built
I restructured the stylesheet into 21 clearly labeled sections, each with a defined scope. Dead code was removed. Vendor template inheritance was untangled. Styles were reorganized so PDF-specific rules were isolated from web and mobile rules, eliminating the print-from-web rendering issues entirely.
The safety snippet system got a full rebuild to ANSI Z535.6 standards — one .flsnp file per signal word level (Danger, Warning, Caution, Notice) with real signal word text rather than CSS-generated content. This made the snippets portable, auditable, and compliant in a way that CSS-generated text never could be.
I also established heading variants — including "minor" and "label" styles — and formalized output conventions for all three delivery types, so future style decisions had a clear framework to build on.
The result
The stylesheet went from an inherited tangle to a system with intentional structure. PDF, web, and mobile outputs now render from a coherent set of rules rather than fighting over shared styles. The print-from-web issue was resolved. Visual alignment with the Academy portal gave the documentation a consistent product feel for the first time.
More quietly: the next writer who opens this project will find something they can understand.
What this says about how I work
I could have left it alone. The old stylesheet was functional. But "functional" wasn't the right bar anymore — not with a new portal, a growing user base, and the expectation that documentation should feel like part of the product, not an afterthought.
This is the kind of work I'm drawn to: systems that are quietly holding things together but starting to show their seams. I find the seams, figure out what's actually needed, and build something that lasts longer than the next update cycle.