Information types

Definition

Information typingInformation typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary → is the practice of categorizing technical communicationTechnical communicationThe broader discipline that spans the entire product life cycle and reaches general audiences, prospects, and journalists — as distinct from technical writing, which produces user-facing product documentation after a sale.View in glossary → 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 schemaSchemaA formal description of the structure a document or data file must follow: which elements or fields are allowed, in what order, and with which values. Validating content against a schema (DTD, XSD, or RELAX NG for XML; JSON Schema for JSON) catches structural errors before publication.View in glossary →, 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 topicTopicThe smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps.View in glossary → 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, ReferenceConcept, task, referenceDITA XML's three base information types: a concept introduces or explains an idea, a task is a numbered procedure, and a reference is lookup material like a parameter list. This manual's own articles are tagged with the same three types.View in glossary →).
• 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-codeDocs-as-codeTreating documentation like source code: text-based formats, version control, code review, and CI/CD, rather than a separate publishing process.View in glossary →, “topic” simply denotes an atomic unit of content. (In DITADITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary →, 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 MarkdownMarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary →/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 minimalismMinimalism (minimalist writing)A task section contains only what's needed to complete the task — prerequisites, steps, and a few closely related elements — with conceptual and reference material placed elsewhere.View in glossary → and Robert Horn’s Information Mapping. For where this page sits in that history, see Information design and Information Mapping in the site history.

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:

Core distinction

The site applies the same broad information-typing principle used by DITA, but implements it through lightweight Markdown/Astro authoring conventions rather than DITA XML schemas.

Our Markdown templates are practical authoring blueprints, not formal DITA XML schemas, and they do not enforce DITA DTDDTD (Document Type Definition)The oldest XML schema language: it declares which elements and attributes a document may contain, and in what order. DITA XML is distributed with DTDs as well as XSD schemas.View in glossary →/XSDXSD (XML Schema Definition)The W3C schema language for XML, itself written in XML. DITA XML's XSD schemas define which elements each topic type allows; a file that breaks them fails validation, which also constrains what conrefs and conditional text may produce.View in glossary → 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 ToolkitDITA-OT (DITA Open Toolkit)The open-source publishing engine that transforms DITA XML sources, assembled by a ditamap, into target formats such as PDF (via XSL-FO) and HTML.View in glossary → (DITA-OT), processing XML catalogs, XSLTXSLT (XSL Transformations)A language for transforming XML documents into other XML, HTML, or text documents. XML publishing chains such as the DITA Open Toolkit use XSLT stylesheets to produce HTML, or XSL-FO for PDF output.View in glossary →, and XSL-FOXSL-FOA stylesheet language for transforming and laying out XML content for print/PDF output, commonly paired with DITA XML publishing pipelines.View in glossary →.
  • Best suited for: Organizations requiring formal structured authoringStructured authoringWriting content whose markup encodes meaning (this is a warning, this is a step) rather than just visual appearance — enabling automated processing, reuse, and consistency checks that unstructured formats can't support.View in glossary →, 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
OpenAPIOpenAPIA standard, machine-readable format (YAML or JSON) for describing an HTTP API: its endpoints, parameters, request and response schemas, and status codes. Reference documentation can be generated from it, leaving writers to add the usage guidance the description can't carry.View in glossary →	Formal API contract model	Schema validation (JSON Schema, Spectral)	YAML / JSON	Machine-readable HTTP API descriptions, generated references

The table opens on the Overview view; the typing and validation columns stay one selection away. For the reasoning behind this layered presentation, see From tables to layers: progressive disclosure in a documentation table.

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

1. 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.

2. 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.

3. 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.

---

Related toolkit resources

• 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.