If you build it, they will come: Our journey to unified (and discoverable) docs
summary
Company consolidates scattered docs into two portals — a support site and a developer site — built with Hugo and docs-as-code, migrating content from Google Docs, Word and PDFs. API docs are autogenerated from protobuff/OpenAPI and gRPC backends; install guides go paperless and are versioned with hashing. Crowdin handles translations. Vertex AI powers search and analytics. Adoption takes about 2–3 months for nondev contributors. Traffic grows after a marketing mention, but discoverability and interlinking between portals remain ongoing work.
AI-written summary · about
chapters (13)
- 0:00Introduction and context
- 2:04Defining the problem
- 3:47Challenges of the status quo
- 6:55Strategy and intent
- 12:04Identifying user personas
- 15:15A two-portal solution
- 18:32Tools and processes
- 22:19Team adoption and training
- 25:21Navigating changes
- 27:40Globalization strategy
- 29:06Search and discoverability
- 31:44Lessons learned
- 32:34Q&A and conclusion
related talks
40mAll together now: Turning technologists into documentarians
45mUseful and Beautiful Developer Docs and How to Create Them
44mUseful and Beautiful Developer Docs and How to Create Them
40mFrom resistance to adoption: navigating the challenges of docs-like-code
48mUseful and Beautiful Developer Docs and How to Create Them
43mUseful and Beautiful Developer Docs and How to Create Them
35mBuilding Docs like Code: Continuous Integration for Documentation
15mDeveloper portal