Information types

Definition

Information typing is the practice of categorizing technical communication according to the reader’s primary goal and cognitive mode, rather than by product feature or arbitrary document chapter.

Instead of writing monolithic manuals that mix background theory, step-by-step instructions, and syntax tables into an undifferentiated narrative, information typing separates content into three fundamental, functional archetypes:

Concept

“What is it?”

Explains ideas, architecture, principles, background, and relationships. It builds mental models before action.

Task

“How do I do it?”

Provides step-by-step procedures to accomplish a specific goal with a verifiable outcome. Action-oriented and linear.

Reference

“What are the details?”

Provides structured facts, configuration parameters, syntax, and lookup data. Scanned quickly by readers who already know what to do.

These are functional distinctions based on reader intent, not rigid literary categories. Every piece of technical content exists to serve a user need: understanding a system, performing an operation, or looking up exact values.

The three types in practice

To see how the three types operate on the same subject, consider documentation for an API integration:

Information type	Main question	Primary reader intent	Concrete example
Concept	What is it?	Understand principles, architecture, or domain rules	”What is idempotency and why does retry logic require it?”
Task	How do I do it?	Complete a goal through sequential, actionable steps	”How do I authenticate and make my first API request?”
Reference	What are the details?	Look up exact syntax, parameters, schemas, or codes	`POST /users` - parameters, request schema, response schema, status codes

Primary intent and content boundaries

Structuring content by information type does not mean information types are mutually exclusive under all circumstances:

A Concept topic can include a small code snippet or architecture diagram to ground an abstract principle.
A Task topic can include brief conceptual context in its objective or prerequisites to explain why a step is necessary.
A Reference topic routinely contains concrete syntax examples to clarify parameter usage.

The guiding rule is: keep the primary information type clear. Supporting information may appear when necessary, but substantial content serving another reader intent should normally be moved to a dedicated topic of that type and linked. This prevents “Franken-topics” - procedures overwhelmed by pages of architectural theory, or conceptual articles cluttered with exhaustive parameter tables.

Core distinctions: terminology hierarchy

Technical writers encounter terms that are frequently conflated. To keep authoring and architecture rigorous, this site distinguishes between five distinct concepts:

Information type: The communicative purpose and primary reader intent of the content (Concept, Task, Reference).
Topic: A discrete, modular unit of information about a particular subject, structured around a single primary information type. In general technical writing and docs-as-code, “topic” simply denotes an atomic unit of content. (In DITA, by contrast, “topic” carries a formal architectural meaning with strict XML element constraints and inheritance rules.)
Article / Page: The published content or presentation unit delivered to the reader (for example, an individual Markdown/MDX page on this site).
Template: An authoring aid or blueprint outlining recommended sections, headings, and structure for a given information type.
Document format / syntax: The underlying serialization or file markup (such as Markdown, MDX, HTML, XML, or YAML).

In a docs-as-code workflow, an author addresses an information type by adapting an authoring template to draft a self-contained topic, stored in a lightweight document format (such as Markdown) and published as an article.

Frontmatter metadata: contentType

To keep the information architecture machine-readable and consistent across builds, API feeds, and automated checks, documentation pages declare their information type in frontmatter:

---
title: "<Article Title>"
description: "<One-sentence summary>"
contentType: concept # concept | task | reference
---

When it is required: Every standard documentation topic (an article explaining a concept, guiding a task, or documenting reference lookup specifications) must specify contentType.
Accepted values: Strictly lowercase concept, task, or reference.
Intentionally untyped pages: Section indexes (index.mdx), landing/navigation pages (such as /learn or /process with pageType: landing), utility pages (/ask, /about-this-blog with pageType: utility), or architectural overviews (pageType: overview) remain valid without contentType.
Why it exists: Frontmatter metadata enables automated CI validation tests and machine feeds to verify structural consistency without relying on brittle path conventions.

Information typing and DITA

Information typing has a rich history in technical communication, drawing on research such as John Carroll’s minimalism and Robert Horn’s Information Mapping.

Later, DITA (Darwin Information Typing Architecture) provided a formal XML-based architecture for information typing, defining standardized Concept, Task, and Reference topic types:

Concept corresponds functionally to the DITA <concept> topic type.
Task corresponds functionally to the DITA <task> topic type.
Reference corresponds functionally to the DITA <reference> topic type.

However, a fundamental architectural distinction must be understood:

Our Markdown templates are practical authoring blueprints, not formal DITA XML schemas, and they do not enforce DITA DTD/XSD validation rules.

Engineering trade-offs: DITA and docs-as-code

Neither DITA nor Markdown/Astro is universally superior; they represent different engineering trade-offs tailored to different organizational needs:

DITA XML architecture:
- Formal semantic model: Fine-grained semantic tagging (<cmd>, <stepxmp>, <varname>, <filepath>).
- Schema validation: Enforces strict structural grammars via DTD, XML Schema, or RELAX NG. Invalid element order fails the build.
- Specialization & reuse: Sophisticated specialization hierarchies and transclusion mechanisms (<conref>).
- Structured publishing: Workflows powered by the DITA Open Toolkit (DITA-OT), processing XML catalogs, XSLT, and XSL-FO.
- Best suited for: Organizations requiring formal structured authoring, complex product variant matrices, multi-channel PDF/HTML delivery, and centralized enterprise translation workflows.
Markdown/Astro docs-as-code:
- Simpler authoring environment: Content is authored in plain Markdown and MDX that any contributor can read and edit directly.
- Git-native collaboration: Changes go through standard version-control branching, code reviews, and pull requests.
- Low tooling overhead: Uses standard web tooling (Node.js, Astro, Starlight) rather than XML processing pipelines.
- Broad developer participation: Engineers, product managers, and technical writers collaborate within the same repositories.
- Lightweight structural control: Editorial discipline is guided by practical Markdown templates (Concept, Task, Reference) and frontmatter metadata validation (contentType: concept | task | reference) rather than rigid XML schema parsers.
- Best suited for: Fast-moving software projects, developer platforms, and teams seeking seamless integration with modern engineering workflows.

For an in-depth analysis of structured formats and modular architectures, see Structured and unstructured formats and From document to modular document base.

A practical comparison

Different documentation paradigms implement information typing and semantic validation at different levels of formalization:

Approach	Semantic typing	Structural validation	Format	Typical use
Markdown template	Editorial convention	Informal / peer review	Markdown	Team wikis, lightweight project notes
This site (docs-as-code)	Explicit information types + templates + frontmatter	Schema-validated metadata (`contentType`), build checks, tests	Markdown/MDX	Modern docs-as-code, technical guides and portals
DITA	Formal semantic topic types, specialization hierarchies	Schema-enforced (DTD, XSD, RELAX NG)	XML	Enterprise multi-channel documentation, hardware manufacturing
OpenAPI	Formal API contract model	Schema validation (JSON Schema, Spectral)	YAML / JSON	Machine-readable HTTP API descriptions, generated references

DITA and OpenAPI in context

DITA and OpenAPI serve distinct, complementary purposes:

DITA provides an architectural model for human-oriented prose across broad enterprise documentation (hardware, software, user guides, operating manuals).
OpenAPI provides a machine-readable model for HTTP API contracts. It precisely describes endpoints, operations, parameters, request payloads, and response status codes.

OpenAPI is not a general documentation authoring framework for prose, and DITA is not a protocol description language for generating interactive API consoles.

Information typing and API documentation

API documentation offers a clear demonstration of how the three complementary information types interact with machine-readable contracts:

Developer journey across information types: Concept, Task, and Reference.

The three types in API portals

Concept (“What is it?”):
- Example: “What is idempotency and how does the API handle retry tokens?”
- Scope: Architectural overview, security principles (OAuth token lifecycle, scopes), rate-limiting policies, and webhook delivery guarantees.
- Role: Supplies the conceptual foundation developers need to design a reliable integration.
Task (“How do I do it?”):
- Example: “How do I authenticate and make my first API request?”
- Scope: Linear tutorials with explicit prerequisites, credentials configuration, executable curl commands, and expected response validation.
- Role: Guides developers through practical workflows to achieve a concrete, working outcome.
Reference (“What are the exact details?”):
- Example: POST /users - parameters, request schema, response schema, status codes
- Scope: Exact HTTP methods, endpoints, query parameters, header requirements, JSON payload schemas, status codes, and error payloads.
- Role: Provides rapid, scannable lookup during coding and debugging.

OpenAPI and the reference layer

OpenAPI describes an API contract in a machine-readable format. It can underpin or generate much of the reference layer of API documentation (such as interactive consoles, parameter listings, and SDK type definitions).

However, OpenAPI itself is not a substitute for complete documentation:

OpenAPI provides the machine-readable API description and contract.
Reference documentation presents human-oriented lookup information about endpoints, parameters, schemas, and error codes.
Concept and Task content still explains the conceptual models, architectural constraints, and step-by-step developer workflows that an API contract description alone cannot adequately communicate.

A comprehensive API documentation portal successfully combines all three: machine-readable OpenAPI contracts feeding generated reference pages, accompanied by thoughtfully authored Concept articles and Task tutorials.

To start drafting endpoint reference pages, see the API documentation template and explore About this manual’s API.

Concept article template - Practical Markdown authoring template for conceptual articles.
Task article template - Practical Markdown authoring template for procedural, step-by-step guides.
Reference article template - Practical Markdown authoring template for lookup specifications.
API documentation template - Specialized reference template for REST API endpoints.
Example: a well-structured Markdown page - An annotated worked example of a concept article.
Structured and unstructured formats - In-depth comparison of DITA XML and unstructured publishing.