New API Possibilities in ClickHelp (Wave Update)

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

The software industry is increasingly depending on APIs. So the role of API documentation cannot be overstated. More vendors and consumers alike see that dynamics.

Documentation is the foundation for good developer experience.

API documentation is a reference manual containing instructions on effectively using and integrating with an API. API Documentation has traditionally been done using regular content creation and maintenance tools and text editors. But special API description formats can help to automate the documentation process, making it easier for teams to generate and maintain them.

Simplifying document creation through automation presents a massive opportunity for businesses of all kinds to save time, ensure better accuracy, and improve workflows.

When we are talking about API documentation and user manuals docs-as-code approach comes to mind. This approach is about writing and publishing documentation with the same tools and processes developers use to create code.

A new release from ClickHelp — the Wave Update has made substantial steps towards that approach. Now the platform is more open for integrations because API possibilities are expanded here.

After publishing your documentation for the first time, you need to make sure you regularly revisit it to keep your content up-to-date. There is nothing more off-putting to potential users of your API than documentation that is incomplete or inaccurate. ClickHelp has introduced new API methods to connect with other systems and automate content updates efficiently. Don’t think this has been done out of a hat, no pun intended :)

As the ClickHelp team claims — they have gathered a lot of typical use cases from their customers that have served as a basis for introducing new API methods. Such scenarios as:

• Sophisticated External Viewers. Context-sensitive help inside web applications UI can be integrated via an API. So when adding something new to your context help demands now a couple of simple steps: move a new topic to your help topic folder and publish changes:

• Custom format importing. You can import the content to ClickHelp from a format or a tool not supported directly. The new API method helps you implement your own importing logic. That logic reads your custom format and creates content in ClickHelp to match the source document structure.
• Automatic file update. If you have downloadable files that are a part of your online documentation (like sample configuration files, definition files, auto-generated header files, etc.) that are created or handled by some automated procedure, you can upload those files automatically to your ClickHelp File Storage to replace the older versions. That can help you save the time that you usually spend on manual file uploads.
• Synchronizing external articles to your ClickHelp portal. You can have your knowledge base in third-party systems (take Zendesk, for example) but you want your users to have the ability to navigate your user guides and KB articles inside one documentation portal. The great part is that you’ll be able to add new topics and update those that already exist.
• API topics update. New API functions of ClickHelp allow implementing a custom synchronization.

1. Update one or several auto-generated API topics. If you have a user guide with mixed topics (regular ones and API topics), you don’t need to do a manual copy-pasting when auto-generated API documentation changes. Automate this process for replacing the content in such API topics with new HTML autogenerated content inside your user guide.
2. Partial update of API topics. If your ordinary topics, in your ClickHelp platform, contain partially auto-generated content, you can automate even the delicate schemes. For example, get the HTML source of a topic, replace some parts of it with the new autogenerated content, and push the new content back.

Without maintaining effective documentation over time, developers won’t be able to use your API, and you’ll experience a decline in adoption. Every time you update or release a new feature, this should be reflected in the documentation and considered an essential part of shipping your API.

The approach introduced in the Wave update by ClickHelp also fits any other types of developer’s documentation created in specialized tools. It’s great that you can use the same approach to synchronize that content into your ClickHelp documentation portal and keep it up to date in one place with other technical documentation!

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors