Beyond the Spec: Bringing Context to Life with GenAI for API Docs

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

Transcript

1. Beyond the Spec: Bringing Context to Life with GenAI for API Docs Lana Novikova, JetBrains, Writerside
2. 01 Why conceptual information matters 02 What is enough 03 How to automate this using GenAI 04 What’s next Beyond the Spec
3. whoami — • Lana Novikova ◦ Technical writer with 10+ years of experience ◦ Shifting to the product management ◦ Developing product for documentarians by documentarians #Writerside
4. Why conceptual information matters? • Different learning styles: systematic, opportunistic, pragmatic A blog post covering the API developer learning styles
5. Why conceptual information matters? • Different learning styles: systematic, opportunistic, pragmatic • Different roles accessing docs: developers, decision makers, security officers Source: Swagger
6. Challenges with reference-only documentation • Lack of context
7. Challenges with reference-only documentation • Lack of context • Difficulty with onboarding and adoption
8. Challenges with reference-only documentation • Lack of context • Difficulty with onboarding and adoption • Disconnect from the real-world usage
11. 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
12. Example structure • API overview • Authentication and authorization • Getting started • API reference • Examples • Release notes, changelog • Glossary
13. Comparing to Diataxis
14. 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
15. JETBRAINS Proof of concept How AI can help to create draft-quality conceptual docs
16. General schema of the PoC
17. 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.
18. Small demo
19. Feel free to try out Repository Deployed version (will be up for a week or so)
20. Prompt engineering wisdom
21. 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 <detail>] for missing information. - Use clear, actionable steps with examples. - Start with "# Getting Started".
22. 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 <error detail>].
23. 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 <detail> here] Generate a "Glossary" section for API documentation. Context: - Terms: OAuth2, API Key, Access Token Instructions: - Use placeholders for undefined terms: [Insert <term definition>]. - List terms alphabetically with definitions: **Term**: Definition goes here. - Start with "# Glossary".
24. Add TODO comments Ask in a prompt to add TODO: <instructions> 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: `<!-- TODO: Verify the flow with the authentication team -->`. - Mention where the information originates (e.g., meeting notes, spec details). - Use markdown and start with "# Authentication".
25. 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 <tool detail>]. - Format in markdown and ensure alignment with the example.
26. 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
27. jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the writerside… We support API docs @lananovikova10 @svetlana-novikova @lananovikova@techhub.social