Populating documentation templates using AI

You're a technical writer creating API documentation for developers. As a technical writer, you write with both clarity and accuracy, following documentation style standards common in technical style guides. You've gathered a lot of source material {Source Material} in the form of engineering docs, project designs, and more. You've also gathered information from meetings with the project team and have included transcripts of the meetings in {Source Material} as well.

You'll draw upon this {Source Material} to populate a documentation template. A documentation template just specifies a specific pattern for information, putting information into a specific order and arrangement. In this case, you'll create an API overview, populating the API documentation template based on information in the {Source Material}. You'll proceed section by section through the template, with me prompting you with the template sections and including an example each time.

Stick as closely as possible to the {Source Material} for your information. If the information doesn't exist in the {Source Material}, don't invent information. Instead, write "No information available in source material" for that part of the template.

Sounds good? Ready to begin? Here's the first section of the API overview template:

{Template for section 1}

Section 1: API Name and description

• API Name — Clear and concise name of the API
• Description — A succinct overview of the API, its primary function, core benefits, and value it offers to developers.

Here's an example:

{Example for section 1}

API Name: RetailGraph API

Description: The RetailGraph API helps you understand your retail data better. Using special database technology, it shows you how products, customers, and sales information are connected. For example, you can see which products are often bought together, how customers move through your website or store, and who your most influential customers are. This lets you make smarter decisions about marketing and inventory.

{Instructions for section 1}

Now draw upon the {Source Material} and populate this first section of the template — API Name and description.

Here's the source material:

{Source Material}

[Paste in all your source material here]

Great! Strive for richer detail if possible. And as always, stay accurate to the {Source Material}. Now let's move on to section 2. Here's the template for section 2:

{Template for section 2}

Section 2: Getting Started

Before You Begin — Essential information developers need before making their first call. This includes authentication methods (API keys, OAuth, etc) with details on how to obtain and use them, base URLs for different API resources, rate limits, usage quotas, and billing information. Security best practices for interacting with the API should also be highlighted.

{Example for section 2}

Here's an example:

Before You Begin

To start using the RetailGraph API, you will need to:

• Obtain API credentials: Generate your unique API key and secret from the RetailGraph Developer Portal. The API key will be included in the header of every request and the secret should be stored securely.
• Base URL: All requests should be made to the following base URL: https://api.retailgraph.com/v2
• Authentication: RetailGraph uses API Key authentication. Include your API key in the header of every request like so: x-api-key: YOUR_API_KEY
• Rate limits: To ensure optimal performance for all our users, RetailGraph enforces rate limits. You can perform up to 1000 requests per minute. See our developer portal for details on how we handle rate limiting

{Instructions for section 1}

Now draw upon the {Source Material} and populate this second section of the template — Section 2: Getting Started.

After AI responds, follow it with this:

Nice work! You're really amazing. I like how you've added so much detail and how you've followed the structure I gave you. You're doing a really good job! Now let's keep going with the third section. Here's the template:

{Template for section 3}

Section 3: Key capabilities and use cases

• Key capabilities — A bulleted list highlighting the API's main functions. Each capability should be briefly explained to give developers a quick grasp of the potential uses of the API
• Use Cases — Concrete, practical examples of how the API can be applied in different business scenarios. These should be written with the target audience's understanding and knowledge in mind.

{Example for section 3}

Here's an example:

Key capabilities:

• Product relationship analysis: Identify products frequently purchased together, revealing opportunities for cross-selling and promotions, or those which are commonly returned together, highlighting potential issues with quality or compatibility.
• Customer journey mapping: Visualize the steps customers take leading up to a purchase, enabling you to optimize marketing campaigns and the sales funnel.
• Influencer identification: Discover customers with a substantial impact on others' buying decisions, helping you develop targeted influencer marketing strategies.
• Trend visualization: Identify and explore emerging sales patterns and trends through graph-powered analytics enabling data-driven decision making.

Use Cases:

• E-commerce recommendations: Provide personalized product recommendations in real-time to enhance customer experience and boost sales.
• Customer segmentation: Group customers based on their purchasing behaviours, demographics and preferences for targeted marketing campaigns.
• Fraud detection Identify unusual patterns of behaviour in your transactional graph which may indicate fraudulent activity.

{Instructions for section 3}

Now draw upon the {Source Material} and populate this third section of the template — Section 3 — Key capabilities and use cases.

It's looking good! Beautiful work. I especially like that you conform to technical style by being accurate, plain, and concise in the language. I also like the bulleted lists and other structures that make it easy to read this information. Way to go! Now let's move on to the next section. Here's the template for section 4:

{Template for section 4}

Section 4: Technical Details

• Endpoints — A well-structured summary of all available endpoints, the HTTP methods associated with them and the expected data formats for requests and responses. Examples of both successful and error responses should be included, potentially with links to a Postman collection.
• Error handling — Clear guidance for developers on how to handle errors. A list of potential error codes with their meanings and suggested resolutions, as well as the structure of error responses.
• Additional considerations — This section provides additional technical specifications like available SDKs, code examples in various programming languages, pagination details, API versioning and the API's deprecation policy.

{Example for section 4}

Here's an example:

Endpoints

• Get Product Relationships — GET https://api.retailgraph.com/v2/products/{productID}/relationships — returns products frequently bought or returned with the specified product ID. Request body should be formatted as JSON, example response:

  {
      "relationships" : [
          {
              "productId": "B00123",
              "relationshipType" : "frequently_bought_together",
              "strength" : 0.8
          }
      ]
  }
  

• Get Customer Journey — GET https://api.retailgraph.com/v2/customers/{customerID}/journey — Visualizes the customer journey as a series of nodes and relationships.
• Identify Influencers — GET https://api.retailgraph.com/v2/influencers Returns a list of customers identified as influencers based on their network centrality and purchase history.

Error handling

RetailGraph uses conventional HTTP response codes to indicate the outcome of an API request. For a full list of error codes see [Error Codes].

Additional considerations

The RetailGraph API supports pagination, versioning, and offers SDKs for Python, Javascript and Java. See [Pagination and versioning] for more details.

{Instructions for section 4}

Now draw upon the {Source Material} and populate this fourth section of the template: Section 4 — Technical Details.

Nice job. I like the way you draw upon the {Source Material} for the information. Accuracy is really important to me. Above all else, I want users to have credible information. Let's keep going with the rest of the template. The following is the template for section 5.

{Template for section 5}

Section 5: Developer Resources

• Tools — A summary of the different ways that developers can interact with the API, that is, via the console, CLI, SDKs or by making direct requests.
• Support — Information on where and how to seek help when using the API such as support channels, community forums, Stack Overflow, issue trackers, and feedback channels.
• Additional resources — A collection of links to additional documentation like tutorials, quickstarts, blog posts and other pertinent materials.

{Example for section 5}

Here's an example:

Tools

• RetailGraph API Console: Experiment with API requests directly in your browser through our interactive API console, no setup required!
• SDKs Integrate the RetailGraph API seamlessly into your applications using our well documented SDKs for Python, Javascript and Java.
• RetailGraph CLI For developers who prefer the command line, our CLI offers powerful features for interacting with the API.

Support

• RetailGraph Developer Portal — Your hub for extensive documentation, tutorials, and community resources.
• Community Forums: Engage with fellow developers and our team through our forums to seek assistance, share insights and ask questions.
• Github Discussions Raise any issues or feature requests directly with our engineering team.

Additional Resources

• RetailGraph Blog — Stay updated with the latest API developments, use cases, and best practices.

{Instructions for section 5}

Now draw upon the {Source Material} and populate this fifth section of the template: Section 5 — Developer Resources. Again, if the information doesn't exist in the {Source Material}, don't invent information or guess. Instead, write "No information available in source material."

Is there any other material in the {Source Material} that wasn't part of the previous templates that you think might be a good idea to include in the API overview?

You are an expert fact-checker. Your task is to ensure the accuracy of the {Documentation}. The {Source Material} is the authoritative source of truth.

Identify Errors: Carefully compare the{Documentation} against {Source Material}. Look for the following types of errors:

• Factual Errors: Any statements that contradict information in {Source Material}.
• Invented Information (Hallucinations): Details or concepts not explicitly present in {Source Material}.
• Omissions: Important information from {Source Material} missing from {Documentation}.
• Logical inconsistencies: Contradictions or internal inconsistencies within the {Documentation}.

Provide evidence: For each error you identify, do the following:

• Cite the specific section within {Documentation} where the error occurs.
• If possible, provide a quotation from the {Source Material} that either refutes the error or highlights the missing information.
• Offer a possible correction or suggestion for improved accuracy.

Consider external resources: If you're unsure whether something is accurate, consult reliable external sources [include a list of pre-approved sources here, if applicable].

Example to get you started:

Let's say the {Documentation} includes a statement like "The API supports real-time data streaming." If the {Source Material} makes no mention of real-time capabilities, this would be an error (likely a hallucination).

Here's the {Documentation}

[Paste the documentation]

Here's the {Source Material}

[Paste the source material]