Best Practices for Developing API Documentation and Guides¶

Overview¶

Creating comprehensive and user-friendly API documentation and guides is crucial for ensuring developers can effectively use your API. This document outlines best practices for developing API documentation and guides, focusing on clarity, examples, and user-friendliness. Customers churn much less the more integrated they are to our platform. So remember to use guides as a way to sell the many ways that our platform can be integrated and used. The documentation should be both a way to help developers onboard themselves and to inspire new ways to utilize our platform.

Best practices¶

1. Explain Concepts with Examples:

   • When explaining a concept with multiple variables, always include an example.
   • If variables can be used in various combinations for different purposes, provide multiple examples to cover the different use cases.

2. Use Placeholders for IDs:

   • For variables with IDs, use placeholders like {website id} instead of real IDs.
   • Ensure to link to a location where users can find the actual IDs or keys, such as the website UUID or recommendation box key.

3. Include Both SDK/Rest API Documentation and Guides:

   • While detailed SDK and REST API documentation are essential, so are comprehensive guides.
   • Use guides to explain more complex terms and scenarios, as they are easier to understand through step-by-step instructions.

4. Emphasize Examples:

   • Provide numerous examples as they are often easier to understand than prose.
   • Examples should be clear, concise, and relevant to the concept being explained.

5. Start Simple, Then Elaborate:

   • When introducing a new guide or API documentation, start with the simplest example that can easily be copied and pasted.
   • Gradually introduce more complex attributes that might depend on customer-specific data.

Example Structure¶

When showing an example, start with something that can easily be copied and pasted by the user:

async function loadRecoms() {
    var data = {
        websiteUuid: '{website uuid}', 
        requests: [
            {   
                key: '{recom box key}' 
            }
        ]
    };
    var options = {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(data)
    };

    const response = await fetch('https://core.helloretail.com/serve/recoms', options);
    return await response.json();
}

loadRecoms().then((resp) => {
    console.log(resp);
});

After the simple example, provide a more advanced example, where you can add custom parameters such as the hierarchies & brand. Remember to explain the advanced properties, or link to where you can read about them.

hrq = window.hrq || [];
hrq.push([
    "loadRecom",
    // requests:
    [
        {
            // recom box key, found in the recommendations overview
            "key": "{recom box key}",
            "format":"html",
            "context": {
                "hierarchies":[["Clothing","Women"]], 
                "brand": "Nike",
                "urls": ["https://mywebshop.com/my-shoe"]
            }
        }
    ],
    // Callback
    function(result) {
        // Do something with data here.
        if (!result.success) {
            console.error(result.message);
            return;
        } 
        for (let i = 0; i < result.results.length; i++) {
            console.log(result.results[i]);
        }
    }
]);

Additional good practices to consider¶

1. Authentication and Authorization:

   • Provide clear instructions on how to authenticate and authorize API requests.
   • Include examples of how to include tokens or API keys in requests.

2. Error Handling:

   • Document common error codes and their meanings.
   • Provide examples of error responses and suggest possible solutions or debugging tips.

3. Testing and Debugging Tools:

   • Recommend tools and techniques for testing and debugging API integrations.
   • Provide links to Postman collections, Swagger UI, or other relevant tools.

4. Documenting Rate Limits and Quotas:

   • Clearly explain any rate limits or quotas associated with the API.
   • Provide examples of how to handle rate limiting and what responses to expect when limits are exceeded.

5. Using AI generated content:

   • You could ask AI agent (e.g. Copilot or the like) to first look on all changes between your branch and target branch, then summarize the changes in a human-readable format.
   • It is also a good idea to specifically indicate in your query that the result "should be in markdown format and needs to be produced as a whole file which can be directly merged into the main branch of docs project". This should ensure that the AI agent produces the whole file without omitting any part of the content.
   • To guide AI agent further, you could also provide a reference to this file by saying something like "adhere to the guidelines in the file docs/documentation-best-practice.md". You might also want to provide a link to some existing documentation files and say, that those files are good examples of how the content should look like.
   • At the moment of writing this, Copilot seems to be much better integrated with Visual Studio Code than with IntelliJ IDEA, so you might want to use Visual Studio Code for this task, especially for reading GIT diffs and creating new files. However, you could use both VSCode and IntelliJ IDEA for some parts of the tasks/specific prompts and then combine the results in the end.
   • Remember to always review the content generated by AI, as it might not always be accurate or relevant.

Naming¶

Here are a few things to note when it comes to naming:

1. If you are writing about our products e.g. Search & Recommendations, the word should be capitilized
2. JavaScript is spelled with two capital letters
3. Recoms should be written as Recommendations
4. Ecommerce can be written in many ways, e-commerce, Ecommerce etc. We have decided to follow the Shopify naming convention of calling it ecommerce without any dashes or capitilized letters.
5. When we talk about our solutions (Recommendations, Search, Pages etc) we should not talk to them as features, but as solutions.
6. Instead of writing Pi we should write Product Intelligence