In 2023, we introduced many new features, architectural changes, and developer experience enhancements in Medusa. The latest of which is highlighted in our Recap 3 page.
We recognized the importance of making sure the documentation aligns with the core product at the same speed. We knew we had to enforce a docs-as-code approach further to do so. A docs-as-code approach encourages adopting processes, testing practices, and implementations with documentation typically used with code.
As a result, we've created a custom documentation toolkit that we use internally, ranging from low-level documentation generation tools to custom-built documentation websites.
In this article, I'll share with you some of the custom documentation tools we built in 2023 at Medusa and some of the plans we have to continue improving our documentation.
Why Build Custom Tools
Previously, our documentation was built using tools like Docusaurus and Redocly. Our team manually wrote the content within the documentation as Markdown files within the Docusaurus codebase.
While this setup worked initially, it was only a short time until Medusa outgrew it. The quick pace of releases made information in the documentation stale; the large number of API routes slowed down the API Reference; introducing new features like Modules and Workflows raised the need for understandable and easy-to-use references.
Our documentation tools weren't enough anymore. So, we started building a documentation toolkit to resolve our problems and improve the developer experience in our documentation.
Custom REST API Reference
Previously, our REST API Reference website was built using Redocly as part of our main documentation website, built with Docusaurus. While Redocly is a great tool for building an API reference website, we had performance issues due to our wide-reaching commerce API Routes and information within each of those routes.
We explored different existing options, but none satisfied our use case. As a result, we decided to build a custom API Reference website from scratch.
The website is built with Next.js 14, and documentation for Medusa’s API Routes is loaded on demand, improving the website's overall performance. Our designer also created a fresh and clean design for the new API reference.
You can check out the source code here.
References Generator
After introducing the Product and Pricing Modules, we wanted to provide a clear API reference in our documentation for the main interface of each module. We also wanted to improve our existing references, such as the JS Client reference.
To do that, we used Typedoc, a tool that generates documentation from comments in TypeScript source code, with existing and custom plugins relevant to our use case. Some of the plugins we built were:
- A plugin that converts OpenApi Specification (OAS) schemas to their equivalent TSDoc comments. This is especially useful for our JS Client reference as we can reuse the same request and response type details used for the REST API Reference.
- A plugin that uses ESLint to lint code examples in the TSDoc comments.
- A plugin that allows injecting custom frontmatter into Markdown files.
This also allowed us to bring the documentation close to the code, which:
- Mitigates information staleness: as members of our engineering team make changes to the code, they can directly reflect the changes on the documentation in the code's doc-block.
- Improves code readability and maintainability.
- Provides better auto-complete descriptions during development.
This encouraged us to move more of our documentation pages to live closer to the code, which is still ongoing.
Coming Soon: Workflows Diagram Generator
In Recap 3, we introduced Workflows. A workflow is a series of steps that complete a task and can be executed from anywhere. Aside from providing the necessary documentation for Workflows, we also wanted to visualize workflows in the documentation for a better developer experience.
So, we built a tool that creates Mermaid diagrams of workflows used in the Medusa backend, which can be visualized in the documentation.
While we still need to incorporate it in our documentation, we've built the necessary foundation of this tool to make it possible and look forward to adding it to our documentation soon.
You can check out the source code here.
UI Props Generator
In 2023, we introduce Medusa UI, a package of UI components that implement the Medusa design system and allow developers to build customizations in the admin with a consistent design.
In the Medusa UI documentation, we show the props that each component accepts. To ensure that these props remain up-to-date, we created a tool that generates JSON spec files for each component from the source code.
These spec files are then loaded in the Medusa UI documentation website, built on Next.js 14, to display the component's details and props.
This tool is built on top of react-docgen, which extracts details of React components and generates JSON documentation, and Typedoc. As we faced some limitations with Copy to clipboardreact-docgen, we customized its handlers and resolvers to ensure that all props and components were recognized and used Typedoc to fill in any missing details.
You can find the source code of the tool here.
Generate Documentation on Release
Building the tools is one thing, but another important aspect is ensuring the documentation is updated whenever there's a new Medusa release.
So, we've added GitHub actions that run whenever a new release is published, making documentation updates part of the release pipeline.
This GitHub action checks for any updates in the REST APIs, UI props, and general references and opens a pull request with the updates, eliminating the need to make the updates manually.
Notable Documentation Improvements
Aside from the custom documentation toolkit, we've continued improving our documentation to provide a better developer experience. The improvements include:
Added a Recipes section in our documentation, with guided learning paths that you can start and finish at your own pace.
An enhanced search experience with intuitive navigation.
An AI Assistant to provide help during your learning journey.
Future of Docs at Medusa
There are still many more improvements to be made both for our documentation and its underlying tooling and processes. Also, since Medusa’s features now make it suitable for orchestration tooling, developers need to understand Medusa as a framework, which requires building a learning path that teaches Medusa’s concepts from end to end.
While it's difficult to list all of the documentation plans, some of the ideas we have for the near future include:
- Improved documentation structure with better learning paths and guidance.
- Interactive API reference and UI documentation.
- Better feedback collection from users to keep improving our documentation and core product.
If you have any ideas for improvements and new features or find bugs in our documentation, please share them with us on GitHub, Discord, or our social channels.
