How to tear down existing documentation and rewrite docs that actually work - Alexandra White

Documentation quality often collapses under fragmentation—multiple sites, hidden or outdated content, inconsistent voices, and no lifecycle plan—until users can’t reliably find answers. Alexandra White’s core finding is that the fastest path to usable documentation isn’t incremental patching; it’s a deliberate teardown followed by a strategy-driven rebuild anchored in audience needs, brand consistency, and a documented lifecycle for creation, updates, and deprecation.

Her experience at Giant—where she became the sole full-time documentation editor for a cloud product—started with a content audit that exposed deep structural problems. Documentation lived across nine different websites, some password-protected, some trapped in Jira tickets, and others duplicated or left to drift. Engineers and support teams relied on Google search even though key information was inaccessible behind logins, creating a “trade secret” effect. Even when content existed, it often lagged behind code because API docs were single-sourced from code but not reliably updated when the product changed. The public documentation site, intended as the main support hub, was maintained by product teams rather than engineers, and even engineers didn’t always know it existed. Worse, there was no lifecycle plan—once content went live, it stayed there by default.

White frames the rebuild as a management problem as much as a writing problem. To win buy-in, she recommends treating the teardown as a proposal-driven campaign: write an argument that targets stakeholders, not yourself. The proposal should connect documentation overhaul to company goals—at Giant, the ambition to become a top cloud provider depended on whether customers could actually use the product. She emphasizes that the proposal-writing process itself forces clarity: it reveals what’s missing, what’s unstructured, what needs brand identity, and what should be kept, migrated, or retired.

Once approval arrives, execution requires more than rewriting pages. White outlines a content strategy and style guide that unify templates, voice and tone, grammar rules, UI and accessibility rules, and controlled vocabulary so product names stay consistent (including external brand names). She also stresses operational mechanisms: guidelines for submitting new documentation requests, and a deprecation workflow that prevents stale content from lingering. Deprecation can include warnings, redirects, and archiving to avoid users hitting dead ends.

She also argues that “delete” is part of the strategy, not a threat. In her case, she took older documents offline and archived them to prompt updates—because living, outdated documentation is a form of technical debt. The rebuild can be interrupted by organizational shifts; she later had to pause the reorganization when asked to move to a new product. Even so, the process produced lessons she didn’t get to fully implement: user testing was underfunded, and she was told to proceed without it. She recommends budgeting for real user feedback, building empathy for engineers who have competing priorities, and treating documentation as everyone’s job. Finally, she ties inclusivity to culture—documentation reflects how people learn, and diverse teams help anticipate different learning patterns.

In short: teardown works when it’s justified with a stakeholder-ready proposal, rebuilt with audience goals and brand-consistent systems, and governed by lifecycle rules that retire bad content before it misleads users.