Beyond the Spec: Bringing Context to Life with GenAI for API Docs Lana Novikova, JetBrains, Writerside

01 Why conceptual information matters 02 What is enough 03 How to automate this using GenAI 04 What’s next Beyond the Spec

whoami — ● Lana Novikova ○ Technical writer with 10+ years of experience ○ Shifting to the product management ○ Developing product for documentarians by documentarians #Writerside

Why conceptual information matters? ● Different learning styles: systematic, opportunistic, pragmatic A blog post covering the API developer learning styles

Why conceptual information matters? ● Different learning styles: systematic, opportunistic, pragmatic ● Different roles accessing docs: developers, decision makers, security officers Source: Swagger

Challenges with reference-only documentation ● Lack of context

Challenges with reference-only documentation ● Lack of context ● Difficulty with onboarding and adoption

Challenges with reference-only documentation ● Lack of context ● Difficulty with onboarding and adoption ● Disconnect from the real-world usage

No content

No content

Must-needed conceptual information The following are must-have conceptual topics that I recommend to have in API documentation: ● API overview ● Getting started ● Authentication and authorization ● API glossary ● API usage examples ● API versioning and changelog

Example structure ● API overview ● Authentication and authorization ● Getting started ● API reference ● Examples ● Release notes, changelog ● Glossary

Comparing to Diataxis

Example structure ● API overview Explanation ● Authentication and authorization How-to ● Getting started Tutorial ● API reference: Endpoints, Request, Response, Parameters, Headers, Data models, Error Codes Reference ● Examples How-to/Tutorial ● Release notes, changelog Reference ● Glossary Reference

JETBRAINS Proof of concept How AI can help to create draft-quality conceptual docs

General schema of the PoC

A bit more into the model tuning details ● Model: Mistral-8x7B-Instruct-v0.1. Why: Chosen for high-quality text generation tailored for technical writing. ● Tuning Parameters ○ Max Tokens = 1000, ensures concise output. ○ Temperature = 0.3, balances consistency. ○ Top P = 0.8, ensures varied, contextually relevant responses. ○ Repetition Penalty = 1.0, prevents redundancy.

Small demo

Feel free to try out Repository Deployed version (will be up for a week or so)

Prompt engineering wisdom

Adding contextual information Include structured context from the OpenAPI specification and meeting notes to make the prompts more targeted. Pre-process the input to extract relevant sections such as paths, schemas, scopes. Generate a "Getting Started" section for API documentation. Context: - Paths: /accounts, /transactions, /auth - Authentication: OAuth2 with API Keys - Schemas: Account, Transaction - Scopes: read:accounts, write:transactions Instructions: - Include these details in the guide. - Add placeholders like [Insert ] for missing information. - Use clear, actionable steps with examples. - Start with "# Getting Started".

Be specific about formatting If you have a style guide or personal/team preferences, put them into prompt. For example: how would you like to structure certain sections, which style to use for headings, etc. Generate an "Error Handling" section for the API documentation. Formatting Rules: - Use markdown headers (##, ###) for organization. - Include tables for error codes: | Error Code | Description | Resolution | |------------|-----------------------|---------------- --| - Write lists in bullet points for clarity. - Avoid including any stylistic notes in the output. Instructions: - Begin with "# Error Handling". - If any details are missing, use placeholders like [Insert ].

Use placeholders When the model lacks certain information, it sometimes fabricates content. Instead, guide it to use placeholders explicitly When information is missing, use placeholders: [Insert here] Generate a "Glossary" section for API documentation. Context: - Terms: OAuth2, API Key, Access Token Instructions: - Use placeholders for undefined terms: [Insert ]. - List terms alphabetically with definitions: **Term**: Definition goes here. - Start with "# Glossary".

Add TODO comments Ask in a prompt to add TODO: mentioning where the model got this information from (part of a specification, meeting notes, answers) or how to check it. Generate an "Authentication" section for the API. Context: - Security Schemes: OAuth2, Basic Auth - Scopes: read:accounts, write:transactions Instructions: - Include TODO comments for unclear details: ``. - Mention where the information originates (e.g., meeting notes, spec details). - Use markdown and start with "# Authentication".

Use existing templates Use existing community templates, for example from The Good Docs project. The template and the corresponding guide already contains prompt-like information on what certain documentation type should contain and how to fill the sections. Generate a "Quick Start Guide" using The Good Docs Project template. Template Reference: 1. Prerequisites: - Credentials: [Insert details] - Tools: Postman, cURL 2. Steps: - Authenticate using OAuth2. - Make your first API call to `/accounts`. Instructions: - Follow the provided structure strictly. - Add placeholders for missing details like [Insert ]. - Format in markdown and ensure alignment with the example.

More ideas instead of the conclusions ● Tailor documentation dynamically to suit developer personas or specific roles ● Implement OpenAPI Workflows to encapsulate tutorials as programmable, chained calls, streamlining onboarding and advanced use cases. ● Use advanced AI techniques like reasoning chaining and few-shot prompting to provide deeper contextual insights in examples and explanations. ● Incorporate community-generated templates more. ● Create feedback loops that refine generated documentation based on user interactions and error reports. Watch Frank Kilcommins: The API Workflows Specification – Unlocking API Value for Humans and Machines

jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the writerside… We support API docs @lananovikova10 @svetlana-novikova @lananovikova@techhub.social