How we rebuilt Shopify’s developer docs
For almost a year I’ve been working on a major project at Shopify and it’s finally out in the world: On February 12, we relaunched the platform’s developer documentation at Shopify.dev.
Leading this major overhaul was basically why I was hired in the first place, and it’s been a remarkable learning experience. I’m really proud of the result — while also knowing that there remains a lot more work to do. I blogged about our in-depth research process for Shopify’s UX Blog:
This may sound obvious, but this insight [that users’ documentation needs change over time] is what steered us away from organizing our documentation around user personas. Often, UX practitioners bucket users by common personas: for instance, if you were building an app for running a car dealership, you’d probably design different activity flows for the people selling the cars out on the lot (a “salesperson persona”), compared to the mechanics working in the service bay (a “mechanic persona”). This technique allows you to make informed generalizations that address common workflows and user needs.
This clear-cut division of labor is less prevalent in software development. At a larger shop, there may be a vice-president who needs to know about the business opportunity, a chief product officer who needs to know about the platform’s high-level technical capabilities, and a team of devs who need to know the API references in detail. But often, those information needs overlap and blur; sometimes, all those “personas” are, in fact, a single individual — just one who’s progressing through the different stages in their development process.