API Documentation Quick Parts of ClickHelp
by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool
Oh wow, did I have a great vacation! But all things come to an end, and others begin, so I’m here with some great news that I almost missed out being away surfing: the Rainbow release from ClickHelp is here. It is as multifaceted as this beautiful natural phenomenon. There are lots of improvements and new features, like a new dashboard, translation editor, reader UI localization, topic editor updates, and more. You can read about them in this blog post. I’d like to pour out about API documentation quick parts from ClickHelp.
As you know, API is a set of definitions and protocols for building and integrating application software. It’s like a window that allows an application to share data and processes with other applications. A REST API is an application programming interface that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services.
Simply put, when you are interacting with a computer or system to obtain data or execute a function, an API helps you inform what you want from that system so it can understand and address your request. When your phone checks for the latest emails, weather forecasts, or daily news, it sends a bunch of REST API calls.
API documentation is more like developer docs, and less like user docs. It is technical, and it is highly templated — methods, parameters, examples, return codes. And Quick Parts, also referred to as “building blocks,” are reusable templated elements that can be inserted quickly into a document.
To help those who write API documentation, in the Rainbow release, ClickHelp introduced special quick parts for API documentation! They’re going to save a lot of time for technical writers and help them make the docs more consistent.
The tool now has a separate tab on the editor ribbon bar with those API Quick Parts, so it’s easier to find them.
My favorite quick parts here are:
- Response Codes. This element helps you to insert a list of typical response codes (informational, success, error) and you can change their default descriptions according to your documentation needs.
2. Request sample. With this sample in the API documentation, you give the readers a sample code with a presentation of how to call a method. You can change the language (C#, JavaScript, etc.). Now you can create multi-language samples using a combination of tabs and code sample elements rendered without the code box wrapper.
3. Response sample. With this command, another Code Sample block is inserted with an example of a JSON response.
4. HTTP Request. With these elements, you can easily insert sample HTTP calls (GET, POST, PUT, DELETE) to give an example of a URL structure for an API method call.
And that’s not all, of course. So better go and see for yourself what else is there.
Why are these ready elements so great? Before, when I needed to write API documentation, I had to code and style my own quick parts to assemble content so that it looked consistent, or I had to create some templated elements. Now, ClickHelp added the most common API quick parts so I have the ready elements that I can use where required. I already tried to change these typical blocks so that they match my API docs design. It was easy! All the elements are in the Quick Parts list and fully customizable for the documentation.
There were times when I didn’t use quick parts, my mistake. Now I see that API docs are a smashing use case. I can make other typical blocks that I use oftentimes. For example, tables of unique styles so that I don’t need to adapt styles every time; lists with custom bullets; infobox versions — I use three variants with different icons and colors; and the like. The API quick parts are proved to be a powerful piece for a tech writer who can benefit from applying quick parts of ClickHelp.
Sometimes it happens when you use a product for a long time and overjump some useful features. I think I need to read that documentation of ClickHelp all over again maybe I’ll find another valuable stuff that I missed :)
Have a nice day!
Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors
