The Past
I am the product manager for the SaaS product, Apidog. It has been online for over two years and offers a wealth of features related to API development, testing, and documentation. This also means it requires a comprehensive set of help documents.
Previously, we used the tool Docusaurus to maintain our Help Docs. It is a document tool based on Markdown with rich customization features.
However, using this tool was challenging for us.
Firstly, it is a code-based tool, which might be developer-friendly, but for a product manager, modifying anything meant pulling code and making a merge request. I spent a great deal of time trying to understand the logic of Git. This also led to us often neglecting minor optimizations in the documentation because it was simply too cumbersome.
Secondly, it was entirely based on Markdown, which has very limited support for styling beyond plain text. For a long time, our help documentation lacked a decent homepage.
Third, Docusaurus had poor support for multiple languages. Our tool itself offers several languages (English, Japanese, with more to come) and provides help documentation in English and Japanese. However, in Docusaurus, these could only be deployed as two completely separate projects. Moreover, because the Japanese help was maintained by our Japanese operations team, there were often updates in the English documentation that were not synchronized to Japanese.
In mid-2024, we suddenly realized that Apidog itself is a documentation tool (though primarily an API documentation tool). Would it be a good idea to use Apidog directly to maintain its help documentation?
Experimentation
In fact, Apidog is a fairly powerful API documentation tool. It supports visual API design, Markdown and API doc mixing, custom navigation, and custom domains. Many companies use it to maintain their API documentation.
But using Apidog entirely to maintain help documentation was a new experiment.
I thought I should try it. If I could create a beautiful example, perhaps companies using Apidog for API documentation might also use it for their help documentation.
I began this experiment around Septemper 2024.
Apidog directly supports Markdown, so the first step was simple: migrate the documentation originally maintained in Docusaurus over.
One great feature is that Apidog supports a much more powerful syntax than native Markdown. For instance, it includes effects like Card, Image Background, Step, Highlight, and more.
I spent considerable time transforming the existing Markdown help documents, making their style more beautiful and modern.
I also quickly created a document homepage, remedying a previous regret.
However, during this process, I also discovered some shortcomings in Apidog’s documentation capabilities.
For example, it doesn’t support document slugs and uses numbers as URL suffixes instead, which is obviously not good for SEO.
Additionally, it only supports searching within document titles, not the content, which is clearly inadequate for help documentation.
Fortunately, I am the product manager for this product. For me, these are two high-priority demands in the backlog.
This was in October 2024.
New Features
On October 25th, we released version 2.6.26. This version supported custom Slugs and automatic Slug generation based on document names.
On November 15th, version 2.6.31 supported Algolia DocSearch, allowing for full-text document searches.
During this period, we added a Support module to the original Help Docs, with each page representing a frequently asked question from users.
At the same time, we used the API version feature to build Japanese Help Docs. We support publishing multiple versions of documents, and readers can choose which version to read on the page. You can consider each version as a revision or as a different language.
So now, I can directly switch between English/Japanese on the help documentation.
Now, I have a set of beautiful, powerful help documents maintained using our own product. I equipped it with custom domains and navigation, and it looks perfect.
The best part is that there is no longer a need for a pull and MR each time, and each product manager can directly maintain the help documentation for their newly launched features. Efficiency and effectiveness have increased significantly compared to before.
Our technical support team can also directly maintain frequently asked questions from emails or Discord into the Support section, just using Apidog.
All images can be directly uploaded to Apidog space without needing special tools to upload them to a CDN.
In early December, our new version of Apidog Help Docs went live. You can read it at https://docs.apidog.com.
Now I can proudly say that Apidog is an excellent tool for maintaining help documentation and API documentation. Most of the above features are free.
Using Apidog to maintain our help documentation was the best decision I made in the second half of 2024.
