At Medusa, we strive to provide developers with the best experience. Documentation plays a huge role in it, as it guides developers in their journey with the software at hand.
As a technical writer at Medusa, I am heavily involved in the development of our documentation, especially in writing the content. Throughout 2022, our documentation team have put a lot of effort into not only investing more resources into documentation, but look into different ways to improve it.
In this article, I’ll share with you how we went about improving our documentation at Medusa.
What is Medusa
Before diving into our documentation improvement, it’s important to know what Medusa is and how developers use it.
Medusa is an open-source composable commerce platform. Its architecture is made of three main components:
- The server: a headless backend that handles all the business logic and data related to the ecommerce store. It can be connected to any frontend for both the storefront and the admin.
- The storefront: this is the interface that customers use to browse the ecommerce store and make their purchase. We provide a Next.js and Gatsby starter storefronts, but developers have the freedom to create their own by connecting to the storefront REST APIs.
- The admin: this is the interface that merchants use to manage their ecommerce store’s settings and data. We provide a Medusa admin that provides all necessary and advanced functionalities, but developers are free to create their own by connecting to the admin REST APIs.
You can learn more about Medusa’s features and architecture in the documentation.
Why we decided to improve our documentation
At the beginning of 2022, our documentation provided developers with the basic information they needed to run Medusa. Although this was good enough to get them started, it wasn’t enough to guide them through the entire process of developing an ecommerce store.
There were improvements needed regarding the content, the design, the feedback collected, and more. To provide these improvements, we needed to change how we handle our documentation and add more resources into developing it.
How we improved the documentation
View the documentation as a product
The most essential change that helped us implement all improvements is how we manage the documentation. In most software companies, documentation has less of a priority compared to the software, and it is handled as an afterthought.
At Medusa, we early on came to realize that documentation is what can actually drive further adoption of Medusa.
Developers that are curious would be sufficient with a quickstart guide. However, those who actually want to use Medusa to create an ecommerce store for themselves or for their clients require the documentation to explain different concepts and how to implement them.
By recognizing that the documentation is a product, we were able to:
- Recognize priorities for what changes/additions should be made for the documentation. These priorities can be decided on based on company goals, our roadmap, improvements in user experience, and more.
- Plan our work in cycles. We now use Linear to manage our documentation cycles, tasks, and backlog.
- Involve the design team and other teams to further improve our documentation and the experience we provide.
- Be more in sync with the core engineering team to deliver changes to the documentation along with changes in the product. The core engineering team also uses Linear, so both teams can be informed of the work they’re each doing, which allows us to stay in sync.
Refactored our API Reference
Our previous API reference needed serious improvements related to:
- Maintaining it to ensure that all the details in it were updated with continuous releases.
- Providing a good user experience, as it was slow and provided minimal information.
- Offering examples on how to use and run endpoints.
To improve it, we decided that it needed to be fully refactored, both in how it was being generated and in how the website itself was built.
The API reference’s OpenAPI Spec is now generated with every new release, ensuring that it’s never outdated. We also added in the OpenAPI Spec comments in our code (which are used to generate the API reference) examples of running requests with the Medusa JS Client and cURL. In addition, we added examples of expected request or response parameters and of possible errors.
The website was previously built with Gatsby using a custom theme. As part of the refactor, we changed it to run as part of our Docusaurus main documentation and on top of Redocly using the Redocusaurus plugin.
This allowed us to utilize Redocly’s functionalities and features that are tailored towards building API references. This further improves the developer experience.
Completely redesigned the documentation
In the last quarter of 2022, we focused on redesigning the documentation to:
- Improve the user and developer experience of our documentation.
- Restructure the homepage to guide developers to the essential concepts and guides in Medusa.
- Provide a design that is fitting with our brand identity.
Thanks to our design team, we were able to introduce a clean design, a summarized homepage with the essential documentation on how to use Medusa, and improve on existing components used throughout the documentation.
Collect user feedback
An important part of developing any product, including the documentation, is to ensure that your users are actually benefiting from the additions or changes you’re making. We implemented that in different ways.
One way was to include a feedback component at the end of all documentation pages or after certain steps that allows developers to let us know whether they found the content helpful or not, and what could be improved.
This helped us find errors in the documentation that we missed or opportunities to make the documentation clearer.
Furthermore, for each code block, we added a report button. This allows developers to quickly create an issue on GitHub with information on the problem they faced while using that code block.
There’s also a link to report issues in the navigation bar that developers can use at any point while browsing the documentation. This further helps us eliminate issues and errors quickly.
Integrate Vale and ESLint into the Documentation
Style guides are important as it helps maintain a single tone throughout the documentation. It is key to be consistent in how you write the documentation, as developers get used to it while browsing it.
However, it’s one thing to write down a style guide, and another thing to actually apply and enforce it. As humans, we can easily miss certain things, especially for written content. This is especially the case with open source projects, as you have many contributors that look forward to help, but may not know how to follow the style guide.
Similar to how a software has integration or unit tests that are built to make sure changes in the software don’t break the entire system, we implemented tests for our documentation’s style guide using Vale and ESLint.
Vale allows you to define a set of rules for your documentation’s textual content. Then, when ran against your documentation files (such as Markdown files), it shows you any errors in the content based on your rules.
ESLint allows you to check for errors and enforce a programming style for JavaScript. Using plugins, it can be integrated with other languages and formats. Using the eslint-plugin-markdown plugin, we were able to check for errors and inconsistencies in code blocks within the documentation.
We also integrated both tools into our documentation pipeline by ensuring that their tests run on every documentation pull request (PR) in our GitHub repository.
Run User Trials
Collecting user feedback is helpful. However, in order to provide a good developer experience, you need to learn how your developers are actually using your documentation.
The best way to do that is to monitor them using it while performing a task. To do this, we started user trials for our documentation. Every quarter, we’ll run a user trial revolving around a specific task and monitor how participants perform that task.
This is essential when you introduce a new feature into your documentation and want to see how developers use it. Is it actually a good feature? What improvements are needed to make it better?
This is also a good exercise to see what problems developers might run into, how the content or the information architecture can be misleading, and whether we really understand our documentation users or not.
If you’re interested in helping us improve our documentation, learn more about our user trials and how you can become a participant.
What’s next?
Writing this article does not mean we have the best documentation out there, and the journey to improve our documentation doesn’t end here. It’s an ongoing process and collaboration between our different teams and the community behind Medusa. The goal is to ensure that we understand our developers and make the information they need accessible.
What do you think of our improvements on the documentation? And do you have suggestions for further improvements? Let us know below!
Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.
Top comments (5)
i am a huge fan of this; especially the idea of treating documentation like a product. i know that i, at least, have probably chosen a lib or a service that wasn't the best in that category simply because the documentation for it was.
when people compare competing services, what they're really comparing is the documentation. they only learn how the service actually works after they've made their decision!
Thanks grant! I agree. Once we started treating documentation like product, and also like code, we were able to see it more than just putting resources out there. We were able to constantly look for ways to improve it, ask the developers for feedback, and treat it the way we would treat our core product.
Love this!
Keen to hear what other considers some of the best Doc pages?
Did you build the UI from scratch or iterate on a template? Because it looks beautiful and clean, especially loving the dark mode.
Thank you! Our documentation is actually built on Docusaurus, but in the last quarter of 2022 our head of design redesigned all our main components + the look and feel of the website. Some of these components are Docusaurus's UI redesigned, others were built/created by us from scratch.