Frameworks & Strategy

Meta-level frameworks and strategic approaches for API documentation work. This section covers evaluation frameworks for API usability, developer personas, organizational contexts, and market dynamics - the conceptual models that inform how documentation teams plan and execute their work. For technical API architectures and implementation patterns, see API Types & Architectures.

Explore the cognitive dimensions framework:

Cognitive dimensions framework in the style of a flowchart, showing usability and design factors

accessibility

Definition: the practice of designing and creating content, interfaces, and experiences that people with diverse abilities, disabilities, and contexts can perceive, understand, navigate, and interact with effectively

Purpose: ensures API documentation reaches all developers regardless of visual, auditory, motor, or cognitive abilities; guides decisions about color contrast, text sizing, navigation patterns, code example formatting, and content structure to create inclusive documentation experiences

Why this belongs in Frameworks & Strategy: represents a fundamental design philosophy and ethical framework that informs all documentation decisions rather than a specific workflow or tool; a strategic approach to inclusive design that shapes content strategy, IA, and UX - similar to how docs-as-ecosystem frames documentation philosophy rather than describing operational practices

The Complexity of Accessibility: accessibility isn't one-size-fits-all - design choices that improve access for some users may create barriers for others, requiring documentation teams to provide flexible options rather than single "accessible" solutions

Example: light vs. dark mode

Mode	Benefits	Challenges
Light Mode	Better for users with astigmatism, dyslexia, or certain visual processing conditions; higher contrast can improve readability for many	Can cause eye strain for users with light sensitivity, migraines, or who work in low-light environments
Dark Mode	Reduces eye strain for light-sensitive users, better for low-light conditions, can help users with certain forms of photophobia	Can reduce readability for users with astigmatism or visual processing conditions; lower contrast may be harder to read for some

Solution: provide both modes as user-selectable options rather than enforcing a single "accessible" choice, allowing developers to choose what works best for their needs and context; additional accessibility solutions for doc teams -

screen reader compatibility for code examples and interactive elements
keyboard navigation for documentation sites and API explorers
sufficient color contrast in syntax highlighting while maintaining code readability
alternative text for diagrams showing API architecture or data flows
clear heading hierarchy for navigation and comprehension
captions or transcripts for video tutorials
plain language explanations alongside technical terminology

Sources:

cognitive dimensions of API usability

Definition: a framework for evaluating and enhancing API usability by considering both designer and user perspectives to identify usability issues and guide design improvements

Purpose: provides a structured approach to assess API design quality across 12 dimensions, helping documentation teams identify where users might struggle and where documentation can provide the most value; guides documentation planning by highlighting which API aspects need clearer explanation or examples

the 12 dimensions

Dimension	What it evaluates
Abstraction Level	Range of abstraction levels the API exposes and their usability for target developers
Learning Style	Learning requirements and how well they align with developers' available learning styles
Working Framework	Size of the conceptual chunk developers must hold in mind to work effectively - cognitive load
Work-Step Unit	Amount of a task developers complete in a single step
Progressive Evaluation	Degree to which developers can run incomplete code for feedback
Premature Commitment	Number of early decisions developers must make and their consequences
Penetrability	How easily the API facilitates exploration, analysis, and understanding of its components
API Elaboration	Degree to which the API needs adaptation or extension for specific developer needs
API Viscosity	Inherent barriers to change and effort required for developers to make modifications
Consistency	Uniformity and predictability of design, naming conventions, and behavior
Role Expressiveness	How plainly the API communicates the roles and responsibilities of its components
Domain Correspondence	How well the API's structure and terminology map to the problem domain

Example: when documenting an authentication API with high premature commitment, in which developers must choose OAuth vs. API keys early, documentation should provide a clear decision guide upfront rather than burying the comparison deep in reference docs

Sources:

content strategy

Definition: discipline encompassing the planning, development, and management of content across its entire lifecycle; encompasses content creation, governance, delivery, and measurement to meet both user needs and business goals

Purpose: ensures API documentation efforts align with organizational objectives, user needs, and resource constraints by defining what content to create, how to maintain it, who's responsible, and how to measure success

Example: content strategy for API documentation

Priority	Activity	Rationale
Q1	prioritize authentication and getting-started guides	highest-impact pages for new API users
Ongoing	engineer review before publication	validates technical accuracy
Versioning	maintain version-specific documentation	ensures backward compatibility
Metrics	track time-to-first-successful-API-call	measures effectiveness of documentation

Sources:

Diátaxis

Definition: a systematic framework for organizing technical documentation into four distinct content types: tutorials, how-to guides, reference, and explanation - based on whether content serves acquisition or knowledge use, and whether it's focused on practical steps or theoretical knowledge

Purpose: provides documentation teams with a structured approach to content planning and organization by identifying which documentation type to create and how to write it; helps prevent common documentation problems like mixing instructional content with reference material or explanations with tutorials, resulting in clearer, more user-friendly documentation that serves both beginners and experts effectively

the four content types

Content Type	Orientation	Focus	User Question
Tutorial	Learning	Practical steps	"Can you teach me to - ?"
How-to Guide	Goals	Practical steps	"How do I - ?"
Reference	Information	Theoretical knowledge	"What is - ?"
Explanation	Understanding	Theoretical knowledge	"Why - ?"

The Framework's Two Axes:

Acquisition vs. Application: whether users are learning something new, acquisition, or applying existing knowledge to complete work, application
Practical Steps vs. Theoretical Knowledge: whether content focuses on doing, practical steps, or understanding, theoretical knowledge

Example: when documenting a payment API, Diátaxis guides writers to create separate content types rather than combining all approaches into one confusing page

Content Type	Title	Orientation	Focus
Tutorial	"Process your first payment"	Learning	Practical
How-to Guide	"Handle payment failures"	Goals	Practical
Reference	"Payment API reference"	Information	Theoretical
Explanation	"How payment processing works"	Understanding	Theoretical

Sources:

docs-as-ecosystem

Definition: comprehensive framework for treating documentation as a complex, dynamic system managed and nurtured through collaboration across diverse stakeholders rather than as static code or isolated content

Purpose: expands beyond docs-as-code by recognizing that documentation encompasses technical writing, design, community feedback, community management, accessibility, SEO - search engine optimization - UX, and AI tools; encourages holistic, multidisciplinary, and community-centered approaches to creating and maintaining API documentation that foster sustained engagement and collaborative growth

Why this belongs in Frameworks & Strategy: represents a conceptual paradigm shift in how organizations approach documentation rather than a specific operational workflow; docs-as-ecosystem expands the operational approaches of docs-as-code and docs-as-tests into a broader strategic framework that encompasses the full complexity of documentation systems beyond just code management and testing practices

Term	Category	Focus
docs-as-code	`Workflows & Methodologies`	methodology for organizing documentation work using developer tools and processes
docs-as-tests	`Workflows & Methodologies`	concrete practice of running automated tests against documentation
docs-as-ecosystem	`Frameworks & Strategy`	meta-level philosophy and organizational mindset for understanding documentation as a living system with multiple stakeholders, feedback loops, and interdisciplinary components

Example: rather than treating API documentation as markdown files managed only by technical writers, a docs-as-ecosystem approach establishes feedback channels through GitHub discussions, social media, and forums, involves developer relations in analyzing feedback trends, coordinates with product managers on documentation roadmap, and integrates contributions from engineers, community members, and customer support to create living documentation that evolves with community needs

Sources:

domain knowledge

Definition: the understanding of a specific industry, discipline, or activity

Purpose: enables technical writers to communicate effectively with subject matter experts and create accurate, contextually appropriate API documentation; writers with domain knowledge can better assess what information developers need, ask informed questions during research, and identify gaps or inaccuracies in documentation

Example: a technical writer documenting a financial trading API benefits from domain knowledge of trading terminology, market mechanics, and regulatory requirements - allowing them to write clearer explanations of rate limiting during market hours or authentication requirements for different account types

Source: Parson: "API documentation - What software engineers can teach us" by Stephanie Steinhardt

DX

Definition: also known as DevEx, acronym for developer experience; multidisciplinary field that combines principles from human-computer interaction, UX, organizational psychology, and software engineering to optimize development; overall experience developers have when discovering, learning, integrating, and maintaining a software product, API, or tool

Purpose: frames API documentation work within the broader context of how developers interact with an API throughout their journey - from initial discovery to production deployment - helping documentation teams understand that docs are just one touchpoint in the overall developer experience

Example: strong developer experience for a payment API

Focus Area	What It Includes	Why It Matters
Getting Started	Comprehensive guides leading to a successful test transaction	Targets under 10 minutes to first successful transaction, a key DX benchmark
Exploration	Interactive API explorer for testing without writing code	Lowers the barrier to entry for non-developers evaluating the API
SDKs	Libraries in popular languages with consistent patterns	Reduces integration time and cognitive overhead across tech stacks
Error Handling	Clear error messages with links to relevant docs	Keeps developers in flow, troubleshooting without leaving the platform
Community	Active forums for developer support and discussion	Provides peer-driven support and real-world usage examples
Testing Tools	Webhook testing utilities	Enables developers to verify event-driven integrations locally before deployment

Sources:

end-user software engineer

Definition: a framework for categorizing developer work styles, characteristics, and motivations into distinct personas

Purpose: helps documentation teams understand different developer approaches to learning and using APIs, enabling targeted content that matches how each persona works; systematic developers need comprehensive reference documentation, pragmatic developers favor structured guides, and opportunistic developers require quick-start examples and business-focused explanations

the three personas

Persona	Approach	Pride	Documentation Needs
Systematic Developer	Writes code defensively, develops deep understanding before using technology	Building elegant solutions	Comprehensive reference, architectural overviews, edge case documentation
Pragmatic Developer	Writes code methodically, develops enough understanding to use technology	Building robust apps	Structured tutorials, best practices, troubleshooting guides
Opportunistic Developer	Writes code in exploratory fashion, develops enough understanding to solve business problems	Solving business problems	Quickstart guides, business use cases, code examples

Example: when documenting a payment processing API, systematic developers need detailed security architecture documentation, pragmatic developers need step-by-step integration guides with error handling, and opportunistic developers need a five-minute "process your first payment" tutorial

Sources:

Dagstuhl Seminar Proceedings: "What is an End-User Software Engineer?" by Steven Clarke
UW API Docs: Module 4, Lesson 1, "Audience analysis and readers' goals"

information architecture

Definition: also known as IA; the structural design of information environments that uses metadata and taxonomy to organize user content; the practice of organizing, labeling, and structuring content to help users find information and complete tasks

Purpose: enables API documentation teams to create logical, findable, and usable documentation structures by applying principles of organization, navigation, search, and labeling to match how developers think about and use APIs

Example: PawFinder Service API docs display a navigation hierarchy that organizes content by user need - setup, reference, task-based learning - and specifically endpoints by resource type, /pets and /shelters, then by function and/or CRUD operation

Static image of the PawFinder API Documentation homepage, showing the documentation structure in various forms: navigational panel on the left, documentation structure in the content body

Sources:

knowledge management

Definition: also known as KM; organizational discipline focused on creating, structuring, sharing, and maintaining collective knowledge, so that the right information reaches the right people at the right time

Purpose: situates API documentation within a broader organizational context; tech writers frequently work within or alongside knowledge management functions, particularly in support, enterprise, and developer-facing organizations where docs serve as the primary vehicle for capturing and distributing institutional and product knowledge

types of knowledge

Type	Definition	Docs Challenge	API Docs Example
Tacit	acquired through experience and intuitively understood; difficult to articulate or transfer	hardest to capture; exists in the minds of senior engineers and experienced API users	reasons for design decisions; how to debug an obscure edge case
Implicit	undocumented process know-how; awaiting codification	docs gap risk; often lost during team transitions or engineer departures	internal conventions for versioning, unwritten rules about rate limit behavior
Explicit	captured in docs, manuals, guides, and databases; easily shared across teams	most of what docs teams produce; the foundation of API reference and guides	API reference docs, error code tables, getting started guides

KM process

Step	What Happens	API Docs Equivalent
Creation	identify and document existing or new knowledge	writing API reference, capturing tacit knowledge from engineers, documenting new endpoints
Storage	host organizational knowledge in a system for distribution	publishing to a docs site, DAM, or knowledge base; version controlling in a repository
Sharing	communicate processes for knowledge access broadly across the organization	developer portals, internal wikis, search optimization, notification of doc updates

KM tools

KM Tool Type	What It Does	API Docs Equivalent
Document Management System	centralized storage for documents and/or digital assets	DAM, Git repository, docs-as-code platforms
CMS	manages web content with editing and publishing workflows	developer portals, Confluence, readme.com
Wiki	easy-to-edit collaborative knowledge base; risk of outdated content	internal engineering wikis, Notion, Confluence
Intranet	private organizational network for internal knowledge sharing	internal API documentation behind authentication
Data warehouse	aggregates data from multiple sources for analysis	analytics platforms tracking doc usage, search queries, time-to-first-successful-API-call

Example: docs teams embedded in KM functions tend to prioritize findability, taxonomy, content reuse, and governance; approaching API docs as a knowledge asset to maintain rather than a shipping artifact to produce; this contrasts with engineering-embedded teams, who often prioritize docs-as-code workflows, and marketing-embedded teams, who emphasize sales collateral and developer acquisition

Organizational Home	Documentation Priorities	Common Tools and Approaches
Knowledge Management	findability, taxonomy, governance, content reuse	DAM, structured content, metadata
Engineering	accuracy, versioning, automation, CI/CD integration	docs-as-code, docs-as-tests, static site generators
Marketing	developer acquisition, use cases, sales collateral	landing pages, tutorials, API overviews
Support	troubleshooting, error resolution, FAQs	knowledge bases, search optimization

Sources:

market

Definition: the space in which customers access a company or products that compete with similar offerings

Purpose: influences content priorities and documentation strategy based on competitive positioning, as an open source API competing in a crowded marketplace needs different documentation emphasis than a proprietary enterprise API with few alternatives; market position determines whether documentation should focus on differentiation, ease of adoption, or enterprise features

Example: a new authentication API entering a market dominated by established players needs documentation that highlights unique features and migration guides from competitors, while an established API can focus on advanced use cases and optimization

Source: Docs By Design: "Audience, Market, Product Webinar"

ontology

Definition: in information science, a formal, explicit specification of concepts, categories, and relationships within a domain that defines what entities exist, what properties they have, and how they relate to each other

Purpose: enables API documentation teams to build shared understanding of domain concepts across writers, engineers, and tools; provides the semantic foundation that powers knowledge graphs, improves search relevance, and enables AI systems to reason about documentation content - going beyond taxonomy's hierarchical classification to capture richer, more nuanced relationships between concepts

Why this belongs in Frameworks & Strategy: represents a foundational conceptual model for organizing domain knowledge rather than a specific tool or operational practice; ontology is the meta-level framework that informs how tech writers structure taxonomy, information architecture, and knowledge graphs, similar to how docs-as-ecosystem frames documentation philosophy rather than describing specific workflows

ontology vs taxonomy

	Taxonomy	Ontology
Primary Function	classifies concepts hierarchically	defines concepts, their properties, and relationships
Structure	tree: parent → child categories	graph: nodes with properties and named relationships
Example	`Authentication` → `OAuth 2.0` → `Token Management`	`Refresh Token` is a type of `Token`, has property `expiration_window`, replaces `Access Token` when it expires
Answers	"What category does this belong to?"	"What is this, what can it do, and how does it connect to everything else?"

Is this glossary an ontology?

ADG, API Docs Glossary, practices ontology-informed thinking without implementing a formal ontology. The Related Terms links define named relationships between concepts, category placement defines what kind of thing each term is, and Why this belongs in fields make classification rules explicit - all ontological practices. However, a formal ontology would express these relationships in a machine-readable specification like OWL or RDF so a system could reason over them, rather than in human-readable Markdown. ADG is better described as an ontology-informed taxonomy - applying ontological thinking to documentation without the computational overhead of a formal specification.

Example: a payments API docs team builds an ontology to support AI-assisted search and content recommendations; because the ontology defines how concepts connect, a search for "payment failure" surfaces not just pages containing those words but also related webhook events, error code references, and troubleshooting guides -

Concept	Type	Properties	Relationships
`Payment`	Entity	`amount`, `currency`, `status`	initiates → `Transaction`
`Transaction`	Entity	`id`, `timestamp`, `result`	requires → `Authentication`
`Webhook`	Entity	`event_type`, `endpoint_url`	triggers on → `Payment` status change
`Error Code`	Entity	`code`, `http_status`, `message`	describes failure of → `Transaction`

Sources:

sales collateral

Definition: materials used internally to inform sales representatives or externally to educate and convert prospective customers

Purpose: bridges the gap between technical documentation and business value communication; technical writers often create or contribute to sales collateral by translating API capabilities into business benefits, use cases, and return on investment (ROI) narratives that sales teams and prospects can understand without deep technical knowledge

Example: a technical writer transforms detailed webhook documentation into a one-page sales sheet explaining how real-time notifications reduce customer support tickets by 40%, using non-technical language and business metrics

Sources:

self-healing system

Definition: architectural design philosophy where a system automatically detects failures, inconsistencies, or drift from an expected state and recovers with little and/or without human intervention — in API documentation contexts, a docs ecosystem that identifies inaccuracies caused by product changes and surfaces or resolves them through automated testing and validation

Purpose: reduces docs drift by shifting from reactive maintenance — fixing docs after users report errors — to proactive, automated detection; in API docs workflows, docs-as-tests implementations create self-healing properties by running continuous validation against live APIs, catching broken endpoints, outdated parameters, or inaccurate code examples before they reach users

Why this belongs in Frameworks & Strategy: describes a strategic approach to system resilience rather than a specific tool or operational workflow; not a methodology, but a conceptual model that informs how docs teams architect their validation pipelines and plan for long-term accuracy; Workflows & Methodologies covers the operational practices like docs-as-tests that implement self-healing properties, while Frameworks & Strategy covers the strategic thinking that motivates those practices

SH-docs vs. SH-API

	self-healing API	self-healing docs
Layer	infrastructure	documentation
Detects	dropped connections, timeouts, cascading errors	divergence between documented and actual behavior
Recovery Method	automatically restoring failed connections	flagging inaccuracies for correction
Philosophy	detect, recover, adapt	detect, recover, adapt

Example: self-healing system workflow with Doc Detective -

Flowchart showing steps: docs team maintains API, runs Doc Detective against API, product ships breaking changes, tests fail, failure alerts fire, tech writers update docs, team works towards automation

Sources:

skunkworks

Definition: a group within an organization given high autonomy and freedom from bureaucracy to work on advanced or experimental projects

Purpose: affects documentation approach for APIs and features developed in skunkworks environments as these projects often have minimal initial documentation, rapid iteration cycles, and uncertain futures, requiring flexible documentation strategies that balance thoroughness with the reality that features may change dramatically or risk discontinuation

Example: a skunkworks team building an experimental machine learning API may need lightweight, frequently updated documentation focused on current capabilities rather than comprehensive reference materials, with clear disclaimers about experimental status

Related Terms: Agile, project management methodologies

Sources:

taxonomy

Definition: hierarchical classification system that organizes concepts, terms, or entities into categories and subcategories based on their relationships and characteristics

Purpose: provides consistent structure for organizing and navigating API documentation, enabling users to find related endpoints, understand conceptual relationships, and build mental models of how API components relate to each other

taxonomy scope

Build Stage - Layer	Concept	Capability Unlocked
Stage 1: Foundation	Technical Comm → Content	Create documentation
Stage 2: Structure	+ Structured Content	Reuse components systematically
Stage 3: Organization	+ Taxonomy + Metadata	Classify, search, and describe content
Stage 4: Intelligence	+ Knowledge Graph	Understand semantic relationships
Stage 5: Dynamic Delivery	+ Modular/Kinetic/Liquid	AI-assisted, adaptive documentation experiences

Example: an API documentation taxonomy might organize endpoints hierarchically or categorize error codes:

Component	Organization
Endpoints	`Authentication` → `OAuth 2.0` → `Token Management` → `Refresh Token Endpoint`
Error Codes	`Client Errors (4xx)` → `Authentication Errors` → `401 Unauthorized`, `403 Forbidden`

Sources:

technical communication

Definition: also known as tech comm; professional field focused on creating documentation, instructions, and informational materials that help people accomplish specific tasks or understand technical concepts

Purpose: establishes the discipline within which API documentation practices, tools, and methodologies exist; encompasses writing, information design, user experience, and content strategy for technical audiences

Why this belongs in Frameworks & Strategy: represents the overarching professional discipline and conceptual framework that contains all API documentation work; Core Concepts focuses on API-specific fundamentals - endpoints, authentication, responses - while technical communication is the meta-level field that defines the nature of documentation work itself - similar to how docs-as-ecosystem frames documentation philosophy rather than describing specific API concepts

tech comm scope

Example: API reference documentation, SDK tutorials, developer guides, installation instructions, and troubleshooting articles are all forms of technical communication created by technical communicators working in the API documentation domain

Sources:

UX

Definition: acronym for user experience; multidisciplinary field involving many stakeholders, drawing on principles from design, psychology, engineering and business; encompasses all aspects of a person's interaction with a product, service, or system, including their perceptions, emotions, and responses before, during, and after use

Purpose: guides API documentation decisions by focusing on DX, developer experience - how developers feel when discovering, learning, and using an API - ensuring documentation reduces friction, builds confidence, and supports successful integration

Example: improving API documentation UX

Focus Area	Action	Impact
Interactivity	Add code examples developers can test immediately	Reduces friction between reading docs and first API call
Error Handling	Provide clear error messages with actionable solutions	Helps developers troubleshoot without leaving documentation
Content Organization	Surface authentication requirements before first API call	Prevents common blocker where developers attempt calls before authenticating
Code Samples	Ensure samples work copy-paste without modification	Eliminates guesswork and reduces time-to-first-successful-API-call

Sources:

white-labeling

Definition: practice of rebranding a product or service for different clients or markets while maintaining the same underlying capability

Purpose: enables companies to offer customized documentation experiences for different customer segments without duplicating effort; in API documentation, allows maintaining multiple branded versions of docs that share core technical content but differ in branding, terminology, examples, and customer-specific features

Example: a payments API provider serves three banking clients with white-labeled API docs; all three sites share identical endpoint references, authentication flows, and error codes stored as Markdown includes, but each displays different branding, custom domain names, client-specific webhook URLs, and compliance disclaimers; when an API endpoint changes, updating the shared include file propagates the change across all three branded documentation sites

Related Terms: monorepo, partials, polyrepo, static site generator

Sources:

accessibility​

cognitive dimensions of API usability​

the 12 dimensions​

content strategy​

Diátaxis​

the four content types​

docs-as-ecosystem​

domain knowledge​

DX​

end-user software engineer​

the three personas​

information architecture​

knowledge management​

types of knowledge​

KM process​

KM tools​

market​

ontology​

ontology vs taxonomy​

Is this glossary an ontology?​

sales collateral​

self-healing system​

SH-docs vs. SH-API​

skunkworks​

taxonomy​

taxonomy scope​

technical communication​

tech comm scope​

UX​

white-labeling​

accessibility

cognitive dimensions of API usability

the 12 dimensions

content strategy

Diátaxis

the four content types

docs-as-ecosystem

domain knowledge

DX

end-user software engineer

the three personas

information architecture

knowledge management

types of knowledge

KM process

KM tools

market

ontology

ontology vs taxonomy

Is this glossary an ontology?

sales collateral

self-healing system

SH-docs vs. SH-API

skunkworks

taxonomy

taxonomy scope

technical communication

tech comm scope

UX

white-labeling