From resistance to adoption: navigating the challenges of docs-like-code
summary
Concrete, step‑by‑step playbook: the ABCs: assess build convince framework, a migration workflow using markdown, git, a static site generator and a Node script, and a demo that gets a preview first page in 30 minutes. Describes converting roughly 100 helpdocs, adding blogs, surviving git conflicts with three non‑dev testers (two become helpers), and claims the platform shift helped scale a product from about 15 to over 100,000 merchants — so expect practical migration costs, objections and scripts you can reuse.
AI-written summary · about
chapters (8)
- 0:00Start
- 13:31Scope and size the migration
- 14:02Test with an outsider for one
- 20:00Find the transformation
- 21:41Prehandle objections
- 25:02Presentation
- 26:21How scary was docs-as-code to approach?
- 27:27How fast was the learning curve?
related talks
48mUseful and Beautiful Developer Docs and How to Create Them
35mBuilding Docs like Code: Continuous Integration for Documentation
44mPushing documentation (so it doesn't hurt anymore)
51mWriting the Darn Docs
45mOne AWS team’s move to docs as code
45mDocs as Code Fix a poor documentation culture in your organization
45mUseful and Beautiful Developer Docs and How to Create Them
44mUseful and Beautiful Developer Docs and How to Create Them