Learn how to deploy Medusa on AWS with Microtica
Medusa won the Golden Kitty Award for Best Ecommerce Product ✨ Learn More
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.
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:
You can learn more about Medusa’s features and architecture in the 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.
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:
Our previous API reference needed serious improvements related to:
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.
In the last quarter of 2022, we focused on redesigning the documentation to:
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.
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.
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.
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.
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.
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.
Learn how to deploy Medusa on AWS with Microtica
This article first discusses the basics of ecommerce APIs and an in-depth evaluation of an open source ecommerce API-first solution —Medusa.