The Challenge
GoDaddy’s developer ecosystem portal needed to migrate from the old classic-developer.godaddy.com to a rebuilt developer.godaddy.com in six weeks as the sole writer, serving two distinct developer audiences (platform app builders and direct API consumers) across Domains, Commerce, and Platform APIs. The goal was quality parity with best-in-class developer docs like Stripe and Cloudflare, measured against a 12-category documentation eval framework rather than subjective review.
The Solution
I restructured the site’s information architecture, audited and rewrote content against the Diátaxis framework, brought 23 OpenAPI specs up to a consistent style standard, and shipped a first tier of documentation-infrastructure improvements, all solo and coordinated with senior engineers and VPs.
Key Initiatives
Information Architecture Restructured the site around two distinct developer audiences: platform app builders (OAuth-based, godaddy.toml, webhooks) and direct API consumers (PAT auth, Domains/Commerce endpoints). Renamed and reorganized the nav hierarchy across both sections, establishing a two-root architecture that shipped via coordinated PRs with senior engineering review.
Content Quality (Diátaxis Framework) Audited all 34 MDX files in the api-users section against the Diátaxis framework, classifying each by severity (10 HIGH, 14 MEDIUM, 3 LOW), identifying four cross-cutting issues affecting 60%+ of files, and scoping ~54 hours of remediation across 5 batches. Rewrote the two highest-priority files (domain registration, payment profile setup) to establish the pattern: prerequisites, goal sentence, numbered imperative steps, verification. Codified the pattern into a reusable agent skill.
OpenAPI Spec Work
Established a style guide (imperative fragments, no terminal punctuation, consistent parameter/response conventions) for all 23 API specs across three spec groups: external legacy, domain/internal, and Commerce platform. Audited ~374 field changes needed and scoped them into per-spec PRs for manageable review burden. Integrated the v3 Domains API into the docs pipeline, including bearer PAT auth migration, a single-domain availability endpoint, and a price unit correction (÷100, not ÷1,000,000). Built a bundler-level stripPrivatePaths() function to durably suppress x-visibility:private endpoints from published reference docs.
Documentation Quality Score To benchmark quality objectively rather than relying on subjective review, I evaluated the site against a 12-category documentation framework (covering things like structural completeness, code-example coverage, cross-linking, and machine-readability, like schema markup and llms.txt) scored against competitors Cloudflare and Stripe (both 90–95 on this scale) as the target bar for developer documentation. The site started at ~57.
In the six-week window, I shipped:
Tier 1
- JSON-LD structured data (like BreadcrumbList, TechnicalArticle, HowTo, and APIReference schemas)
- Canonical URLs
- Frontmatter-driven “Related” and “AgentNotes” components
- An
llms.txtrestructure - Automatic reference-page generation
Tier 2 (majority complete)
- Dedicated troubleshooting pages
- End-to-end workflow journey pages
- Multi-language code samples (curl + JS fetch) across the search, registration, and DNS endpoints
That work raised the score to 64. The remaining gap to Cloudflare/Stripe-level parity is scoped into further Tier 2/3 work, largely around deeper workflow coverage and expanded example diversity.
Key Technologies
Next.js · Fumadocs · MDX · TypeScript · OpenAPI 3.x · JSON-LD / schema.org · Tailwind CSS · GitHub Actions · Mermaid