On March 15th, we rolled out a new Medusa documentation with a cleaner design and a straightforward structure. This is part of our mission to constantly improve our developer experience and help guide developers in their journey using Medusa.
In this article, I’ll detail the thought process, planning, and general work that went into revamping our documentation.
Problems with the Previous Documentation
A few months back, I wrote an article about how we improved our documentation at Medusa. In that article, I discussed why and how we decided to take a product approach towards documentation.
This lead to an improvement to our documentation from its initial state both in design, structure, and development tools and processes.
However, it wasn’t long until we realized that although this was a huge improvement, it was still lacking in different areas.
Documentation Structure
Our approach to structure was simple: if a documentation page was a tutorial or a guide that informed developers how to perform something, we put it under the “How-to Guides” category; if a documentation page was a conceptual guide explaining how a feature or a tool generally works, we put it under the “Conceptual Guides” category.
Although we believe in the beauty of simplicity, this approach was too simple for a solution like Medusa. Medusa is not an ecommerce platform that can be used in a single use case. Medusa provides the building blocks to build commerce applications. It can be used to create a fully-fledged ecommerce system, or some of its modules can be used within a larger microservice or composable architecture.
So, categorizing documentation pages that may cover topics related to the Medusa backend, the storefront, the admin, or other areas under general categories such as “How-to Guides” or “Conceptual Guides” became limiting. It made it difficult for developers to find the guide they’re looking for in a specific area, and it was misguiding, as it didn’t properly inform developers of the different ways they can use Medusa.
Documentation Design
The previous design was a major step-up from the initial design we had, but it mainly lacked in visual elements that can help developers differentiate between different sections or areas of the documentation.
In addition, while performing user trials — where we ask developers to use our documentation to perform a task in Medusa — we received comments about some confusion while using the sidebar due to how it was designed.
Planning for the New Documentation
As documentation is essential for a pleasant developer experience, our documentation team decided it was time to look into how we can improve our documentation.
Figuring out the Information Architecture
We started off by building a new information architecture for the documentation. We created a hierarchy of the areas in Medusa, starting from the too-general categories and getting down to specifics.
For example, in the previous architecture, we stuffed the How-to category with guides that were not remotely related to one another. So, you would find a guide on how to implement a cart in the storefront right next to a guide on how to create an endpoint.
We started de-structuring that architecture to find the top-level main areas of interest, and work our way down from there. These areas ended up being Commerce Modules — which covered all guides related to commerce features, such as the implement cart guide — and Medusa Development — which covered the fundamentals of developing with Medusa, such as the create endpoint guide.
Then, we would dive into the structure of each of these top-level areas and work our way down from there. For example, inside Commerce Modules, the guides should be categorized by each module. Within the category of each module, we categorized the guides based on whether they’re architectural guides or how-to guides, and what areas do these guides tackle (for example, admin or storefront).
Taking this granular approach towards categorizing the documentation can easily become too confusing. So, it was important to also design a journey that allows developers to find their next steps and not get lost within this architecture. This was a combination of writing an informative content structure and providing visual elements and effects to make the journey even clearer to developers.
Re-designing the Documentation
After coming up with the initial draft of our new information architecture, we started working on the design to bring it to life. The redesigning of the documentation involved redesigning existing elements and creating new elements that provided visual values.
For example, we moved towards using descriptive icons in our main sidebar. We also redesigned the global sidebar within the documentation to ensure the categorizing and hierarchy is visually visible and clear.
Part of the redesign was also maintaining a consistent design system within our products at Medusa. So, the documentation now uses the same design system that products like the Admin use.
Building the New Documentation
The last piece of the puzzle was building the new documentation. This included modifying existing functionalities and components, building new components, and reflecting the Medusa design system into the documentation.
One component we changed was the Feedback component that can be seen at the end of documentation pages. Although this component provided us with insightful feedback from developers using our documentation, we realized that we weren’t actually providing developers with any solutions if they run into any problems.
So, we revamped the Feedback component that provides possible solutions from closed GitHub issues. The issues are shown either based on the message that the developer enters, or based on the page they’re in.
The Final Result
The new documentation was a product of a lot of discussions and brainstorming to come up with an improved developer experience. After numerous rounds of iterations and improvements, we decided to roll out the new documentation.
As always, this in no way means that the documentation is now perfect or finished, and it should be no surprise if later in the year you find another article on how we — again — improved our documentation. Documentation is a continuous learning and growing experience as we further understand developers using Medusa, and as we further innovate with Medusa.
We look forward to any feedback you have, which you can always send on our Discord, GitHub issues and discussion, or using the feedback form within our documentation.
