A tricky aspect of documenting an API is when you have to redefine a word in the context of your API. For example, in the context of the Compose API the word “Recipe” is defined as:
A recipe is a process, or processes, which performs a particular task. Some endpoints in the API return a recipe. This contains the details of the recipe that has been started and includes an id for the recipe and its status. The recipe runs asynchronously and an endpoint allows applications to poll for the current status of any recipe they have the id of.
While this is similar in some ways to the contemporary definition of the word, there are additional modifications to the definition that might be important to the end user. But as an end user, it can be hard to remember all of these modified definitions. And what happens if they never went to the page where the word was originally redefined?
That’s why we built ReadMe Glossary. So how does it work?
1. Create Glossary Item
Go to the new Glossary Tab and create a Glossary Item.
2. Add it to your Docs
While editing a page simply type <<YOUR_GLOSSARY_TERM to start searching through all of the glossary words you’ve created.
3. Delight your end user
As an API Documentation company we’re constantly asking ourselves how we can help the end user of an API better understand the API they are consuming. We hope this feature will move us forward in that direction!