How we rebuilt Shopify’s developer docs (again)
Most of my 2021 at work was devoted to evolving the next iteration of Shopify.dev, Shopify’s developer documentation platform. When we originally launched the site in February 2020, I blogged about the information architecture design process, and since the changes since then have been quite substantial, I wanted to do it again.
This time, it’s all about what we learned during the first year of the site’s life, and what we decided to change as a result of our observations:
Grouping by information type — conceptual information, tutorial information, reference information — made perfect sense on paper but didn’t work as well in practice. Tutorial content, in particular, struggled under this model, because sheer volume made it hard to do second-order navigation. If you ever landed on this page, with hundreds of individual tutorials forming a wall of text, then you felt this pain as you hunted for the particular problem you needed to solve. We experimented with a bunch of design ideas to mitigate this issue but none of them ever broke the logjam.
Grouping by information type had a second flaw that was less obvious but became clearer over time as we talked to more developers in the community. What our users needed from us wasn’t just information, but direction. Our docs were good at describing the different parts of the platform and individual developer tasks, but we hadn’t strung them together into a clear narrative. New users arrived at the site thinking, “I just want to build a theme”, or “I just want to build an app”, and we weren’t clearly laying that process out for them. All the pieces of the puzzle were there, scattered around various parts of the site, but we hadn’t been opinionated enough about Shopify’s vision of what a great app or theme looked like.
Previously: How we rebuilt Shopify’s developer docs