Looking to streamline your product documentation process without requiring technical expertise? Apidog offers a comprehensive solution that empowers product managers and operations teams to collaborate seamlessly on creating, managing, and publishing professional documentation. With its intuitive interface, real-time collaboration features, and zero-maintenance publishing, Apidog transforms how teams approach documentation workflows.
Every product needs its own documentation. Even if your product is a consumer-facing application with very intuitive and simple interaction design, there will still be areas that need more explanation, but would add complexity if presented directly in the product interface. Therefore, document management, maintenance, and publishing are crucial concerns for every product.
When building product documentation, teams typically use out-of-the-box documentation tools like Notion, or content management tools like Confluence and CMS, or documentation generators like Docusaurus and Gitbook. However, these solutions often encounter the following issues:
- Documentation requires coding to write, with high costs. Even after the documentation is written, the actual reading experience often falls short of expectations;
- Documentation involves multiple roles collaborating, making version management difficult and making it hard to communicate optimization suggestions to others;
- Publishing finished documentation to the production environment is either too simple or too complex, potentially involving engineering processes that are difficult for non-technical colleagues to handle, leading to errors.
The Apidog team previously used Docusaurus to create our documentation. As our documentation continued to iterate, we also encountered some of the problems mentioned above. After summarizing our experiences and lessons learned, we developed solutions and integrated them into Apidog. Now, the Apidog team's product documentation has been completely migrated to Apidog, with all creation and presentation handled by Apidog.
I'll share our practice of how to build product documentation through Apidog. Before that, if you want to take a closer look at the specific effects of Apidog's product documentation, you can check out the Apidog help documentation - feedback is welcome.
Background
Before introducing our practice, there are some contexts that may need to be explained first, so that everyone can better understand why we do things this way. Our company's product documentation is generally collaboratively created by product and operations department colleagues. The main process is as follows:
The above process requires no technical personnel involvement - all product documentation-related operations are completed by colleagues from these two departments. Next, I'll explain how to complete the task of building product documentation through Apidog according to this process.
Core Process
1. Create a Sprint Branch for Content Management and Collaboration
After a development iteration begins, operations colleagues create an iteration branch in Apidog to place all documents involving changes in the current iteration within this branch for collaboration, avoiding direct impact on the main branch.
After creation, product managers import existing documents that need modification into this iteration branch based on the features actually updated in the iteration, and create new documents for new features directly in the iteration branch. The operation here is completely consistent with the usage of iteration branches for API documentation.
Because we've set protection on the main branch, direct changes to document content in the main branch are not allowed. This means you cannot manually modify content in published documentation that users can see directly, making product documentation more stable and reducing situations where random changes lead to incorrect content being seen by users.
2. Use the Beautiful Markdown Editor to Write Each Document
Product managers will use Markdown to write documentation that needs to be updated in the current iteration within the iteration branch. Apidog's Markdown functionality is very powerful, with various visual components that can be clicked to insert many complex styles with a low barrier to entry, allowing you to easily write beautiful articles without spending extra effort.
In addition to general MD style visual insertion, Apidog has added the following special features:
- Insert project APIs/documents, allowing documents to link together forming reference chains with seamless navigation, providing readers with a smoother experience and better solving readers' needs and problems - this is a very important feature.
- Provide rich resource insertion functions, such as Icons, highlight blocks, tables, steps, Mermaid, videos, etc., so you don't have to spend time finding resources yourself or learning MD style syntax to make documents look better.
3. Product/Operations Colleagues Collaborate to Polish Documents
After product managers write the initial version of documents in the iteration branch, to improve document quality, clarity, and user helpfulness, they hand over the documents to operations colleagues to read from the user's perspective and provide modification suggestions for polishing.
This used to be the most time-consuming and laborious part, requiring mutual collaboration between both sides, with one party explaining their ideas and providing specific modification suggestions for certain parts; then the other party receiving, understanding, and actually making the changes. During the back-and-forth process, there were often various problems like misunderstandings, incorrect changes, and content differences between document versions, leading to very low efficiency.
Now using Apidog, both sides can directly make modifications in the documents, with real-time message notifications pushed to IM when changes are made, allowing others to immediately enter the document and easily see specific changes, greatly improving collaboration efficiency. Here are the specific steps:
- Product managers create the initial version of documents. After operations personnel see the notification, they read the document and directly make modifications to content they want to change within this document.
- Modifications automatically trigger notifications upon saving, sending change message cards to the pre-configured IM group. After group members see the change overview message cards, they can click the notification link to enter the relevant document with one click.
- Through modification history, compare differences by selecting the current version and original version to easily view the other party's modifications and decide how to adjust the document. You can choose not to accept suggestions and restore to the original version, or accept modifications and keep the latest version.
Product and operations teams repeat the above steps until document content is polished and a version that everyone approves is determined.
4. Preparation and Review Before Official Document Publication
To ensure that the content and product screenshots in documents are completely consistent with what users can access, we recommend taking screenshots on the product's production environment. This also allows verification that new capabilities launched in the production environment are working properly. After operations personnel use new features online and take screenshots, they add them to the articles.
Operations confirm the completed content documents from this iteration, select them, and submit an MR request to merge into the main branch.
The operations manager or other project administrators review the document content to be published, confirm it's correct, and then choose to merge into the main branch.
After merging is complete, when users access published documents, they can see the latest content merged into the main branch.
Other Advantages
In addition to the capabilities already introduced, Apidog also has the following features in terms of publishing documents to help everyone build product documentation sites that better meet their needs.
1. Set Overall Documentation Site Styles that Match Product/Company Style
You can set the overall style of the published documentation site, making the entire website's style more aligned with your company's tone, and adding more related resources and company content links to give users a better experience.
Apidog's help documentation has set its own logo and some Apidog-related resource links. The upper left contains the company logo, the upper right contains various company-related resource links, and the open API documentation that developers care more about is also set within the product documentation:
2. Zero-Maintenance Publishing Experience
In Apidog, you only need to click the "Publish" button in the publish documentation feature to publish the entire documentation to the internet with one click for your users to read. Apidog officially provides domains for everyone to use, saving a lot of maintenance work.
Of course, if you need to make the documentation more like your own company's website, we also provide custom domain functionality, allowing you to use your own company's domain to access documentation.
You can also easily set up regular search, Algolia full-text search, integrate GA, set redirects, and other advanced capabilities in published product documentation sites with simple operations. These configurations don't require operators to have sufficient engineering capabilities - they can be easily set up by following interface guidance and help documentation.
3. Multiple SEO-Friendly Settings
Apidog automatically generates reasonable Slugs for published documentation sites based on basic settings to better allow users to access and share them.
Of course, if you have more advanced SEO needs, it also supports custom Slug, Meta Data, and various other content settings for each individual document.
Conclusion
The above is the specific practice of using Apidog for product documentation maintenance.
In addition to the content mentioned above, we can also maintain product help documentation, developer documentation, and API documentation in one style and link them all together, providing an even better user experience. If your actual situation is suitable, welcome to try this practice and recommend it to other colleagues. We hope this can bring some efficiency and quality improvements to your product documentation building work..
