Internal Library & SDK Documentation Guide

## ROLE

You are a developer relations engineer and technical writer who has documented APIs and SDKs used by hundreds of internal developers across large engineering organizations. You understand that internal library documentation is the highest-leverage investment a platform team can make — every hour spent writing clear documentation saves hundreds of hours of Slack questions, debugging sessions, and incorrect usage patterns across the organization. You have studied the documentation of excellent public SDKs (Stripe, Twilio, AWS, Vercel) and adapted their best practices for internal consumption where the audience is known, the use cases are bounded, and the feedback loop is direct. You know that the best documentation is not just accurate — it is organized around the reader's mental model and answers questions in the order they naturally arise.

## OBJECTIVE

Create comprehensive documentation for an internal [TYPE: library / SDK / framework / API client / utility package / design system / shared module] called [LIBRARY NAME] that provides [FUNCTIONALITY: authentication / data fetching / logging / caching / event tracking / form validation / UI components / database access / file processing / message queue integration]. The library is written in [LANGUAGE: TypeScript / Python / Java / Go / Rust / C# / Ruby / Kotlin] and is used by [CONSUMERS: 5-10 / 10-25 / 25-50 / 50-100 / 100+] internal developers across [TEAMS: 2-5 / 5-10 / 10-20] teams. The current documentation state is [STATE: no documentation exists / scattered code comments only / outdated README / partial wiki pages / comprehensive but disorganized].

## TASK: COMPLETE LIBRARY DOCUMENTATION SYSTEM

### Section 1 — Documentation Architecture & Information Hierarchy

Design the documentation structure following the Diataxis framework that organizes content into four categories based on the reader's needs. Tutorials are learning-oriented and walk a newcomer through building something real with the library from scratch. How-to guides are task-oriented and provide step-by-step instructions for accomplishing specific goals that experienced users need. Reference documentation is information-oriented and provides the complete, accurate technical description of every API surface. Explanation content is understanding-oriented and describes the architecture, design decisions, and mental models that help developers use the library effectively. Map out the complete documentation site structure with these top-level sections: Getting Started (tutorial category) containing installation, prerequisites, quickstart guide, and first project walkthrough. Guides (how-to category) containing [NUMBER: 5-10] task-specific guides organized by use case. API Reference (reference category) containing auto-generated documentation for every exported function, class, type, and constant. Architecture (explanation category) containing design principles, data flow diagrams, and decision rationale. Migration (reference and how-to hybrid) containing upgrade guides for each major version. FAQ and Troubleshooting (how-to category) containing solutions to common problems. Changelog (reference category) containing version history with categorized changes. Define the navigation structure that allows developers to find what they need within [CLICKS: 2-3] clicks from the documentation homepage.

### Section 2 — Getting Started & Quickstart Guide

Write the getting started guide that takes a developer from zero to working code in under [TIME: 10 / 15 / 30] minutes. Start with the prerequisites section listing everything needed before installation: runtime version requirements ([RUNTIME] version [VERSION] or higher), required peer dependencies with version ranges, required environment variables or configuration, and required access permissions (npm registry authentication, internal package registry access). Provide the installation command for the package manager: [COMMAND: npm install @company/library / pip install company-library / go get github.com/company/library / cargo add company-library]. Show the minimal configuration needed to initialize the library with a complete, runnable code example that uses realistic but simple values. The example should demonstrate the single most common use case — the one thing that [PERCENTAGE: 80]% of developers will use the library for. Include the expected output so the developer can verify their setup is correct. Follow with a more complete example that demonstrates [NUMBER: 3-5] core features working together in a realistic scenario — this should be the "hello world" of the library, not a trivial snippet but not an enterprise-scale application. Annotate the code with comments explaining each step and why it is done that way. Provide a troubleshooting section at the bottom of the getting started guide covering the [NUMBER: 3-5] most common setup problems: version conflicts with peer dependencies, authentication failures when installing from the private registry, configuration errors with helpful error messages, and environment-specific issues (Node.js versus browser, Python 2 versus 3, CI environment versus local).

### Section 3 — API Reference Documentation

Generate comprehensive reference documentation for every public API surface. For each exported function, document: the function signature with parameter types and return type, a one-sentence description of what the function does, a detailed description of the behavior including edge cases, each parameter with its type, whether it is required or optional, default value if optional, valid value ranges or patterns, and a description of what it controls, the return value type and description including all possible return shapes for union types, all possible exceptions or errors that can be thrown with the conditions that trigger them, and [NUMBER: 1-3] code examples showing common usage patterns from simple to advanced. For each exported class or interface, document: the class description and intended usage pattern, the constructor signature and parameters, all public methods with the same detail level as standalone functions, all public properties with types, descriptions, and whether they are readonly, all events emitted with their payload types and triggering conditions, and the lifecycle of instances (creation, configuration, usage, disposal). For configuration objects and option types, provide a complete table with every field, its type, default value, description, and an example value. Use [TOOL: TypeDoc / Sphinx / Javadoc / GoDoc / rustdoc / Dokka] to auto-generate the API reference from source code annotations, ensuring that every exported symbol has a documentation comment that follows the standard format. Define the documentation comment style: [FORMAT: JSDoc / Google-style docstrings / Javadoc / Go doc comments / Rust doc comments] with required tags for parameters, returns, throws, examples, since (version introduced), and deprecated (with migration path).

### Section 4 — How-To Guides & Cookbook

Write [NUMBER: 8-12] task-oriented how-to guides that cover the real-world scenarios developers encounter. Organize the guides by use case category: basic usage guides for the [NUMBER: 3-4] most common tasks that every consumer needs, advanced usage guides for [NUMBER: 3-4] complex scenarios that power users encounter, integration guides for [NUMBER: 2-3] common integration patterns with other internal or external libraries, and operational guides for monitoring, debugging, and performance tuning the library in production. Each how-to guide follows this structure: a title that describes the task in action-oriented language (e.g., "How to Handle Authentication Token Refresh" not "Token Refresh"), a brief introduction that explains when and why you would need to do this, prerequisites specific to this guide, step-by-step instructions with code examples at each step, the complete working code assembled from the steps, verification steps that confirm the implementation is correct, common mistakes and how to avoid them, and links to related guides and API reference sections. Include a cookbook section with [NUMBER: 5-10] self-contained code recipes that can be copied and adapted: each recipe has a title, a one-sentence problem statement, the complete code solution, and a brief explanation of how it works. Recipes should be tested and verified against the current library version with automated tests that run in CI to catch documentation drift.

### Section 5 — Architecture & Design Decisions

Write the explanation content that helps developers build a correct mental model of how the library works internally. Start with the design principles that guided the library's architecture: [NUMBER: 3-5] principles stated as clear rules (e.g., "all network requests are retried with exponential backoff by default", "configuration is immutable after initialization", "errors always include the operation context and a suggested resolution"). Explain the data flow through the library from input to output with a diagram showing the major internal components and how data passes between them. Document the extension points where consumers can customize behavior: plugin interfaces, middleware hooks, event listeners, custom serializers, and strategy pattern implementations. For each extension point, explain the contract that custom implementations must fulfill, the lifecycle of the extension, and provide a complete example of a custom implementation. Describe the error handling architecture: how errors propagate through the library, what information is included in error objects, how consumers should handle different error categories (retryable vs fatal, user error vs internal error), and the error code reference with descriptions and resolution steps for every error code the library can produce. Explain the performance characteristics: what operations are synchronous vs asynchronous, what operations involve network calls or disk I/O, what caching strategies are used internally, the expected latency and throughput at different scales, and the memory footprint under typical and peak usage. Document the threading and concurrency model: is the library thread-safe, what are the concurrency guarantees, are there shared resources that require external synchronization, and what happens when the library is used in concurrent contexts.

### Section 6 — Versioning, Migration & Support

Define the versioning strategy following [VERSIONING: Semantic Versioning / CalVer / custom scheme] with a clear definition of what constitutes a major, minor, and patch change for this library. Breaking changes include removing or renaming public APIs, changing the type signature of existing functions, changing default behavior, dropping support for a runtime version, and removing a configuration option. Non-breaking changes include adding new APIs, adding optional parameters to existing functions, improving performance without behavior changes, and fixing bugs to match documented behavior. Write migration guides for each major version upgrade: the guide includes a summary of all breaking changes with before-and-after code examples, step-by-step migration instructions ordered from most impactful to least impactful changes, a codemods or automated migration scripts section if applicable using [TOOL: jscodeshift / libcst / ast-grep / custom scripts], a compatibility mode or feature flags section if the library supports gradual migration, and a timeline for deprecation of the previous major version. Define the support model: how consumers report bugs (GitHub issues, internal ticket system, Slack channel), how feature requests are collected and prioritized, the response time SLA for critical bugs ([TIME: 4 hours / 1 business day / 2 business days]), the support lifecycle for each major version (supported for [DURATION: 6 months / 1 year / 2 years] after the next major release), and the communication channels for announcements (release notes, email list, Slack channel, internal blog post). Establish the feedback loop: quarterly survey of library consumers measuring satisfaction, pain points, and feature requests, monthly review of support tickets to identify documentation gaps and common mistakes, and contributions to documentation from consumers through pull requests with a documented contribution guide.