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

## 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:

```yaml
---
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:

> **Note: 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 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](https://docs.redaction-technique.org/en/toolkit/concept-article-template/), [Task](https://docs.redaction-technique.org/en/toolkit/task-article-template/), [Reference](https://docs.redaction-technique.org/en/toolkit/reference-article-template/)) 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](https://docs.redaction-technique.org/en/formats/structured-vs-unstructured-formats/) and [From document to modular document base](https://docs.redaction-technique.org/en/formats/modular-documentation/).

---

## 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:

```mermaid
%%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif", "clusterBkg": "#f1f5f9", "clusterBorder": "#64748b"}}}%%
flowchart TD
    accTitle: Developer Journey Across Information Types
    accDescr: Sequential progression across documentation types, from domain concepts to task execution and reference lookup.

    subgraph S1["1. Concept — Understand the domain"]
        C1["What is idempotency?<br/>Architecture, auth model, core domain objects"]
    end

    subgraph S2["2. Task — Perform an operation"]
        T1["How do I make my first API request?<br/>Prerequisites, token exchange, copyable curl steps"]
    end

    subgraph S3["3. Reference — Consult exact details"]
        R1["POST /users — parameters & schemas<br/>HTTP verb, endpoint path, request/response models"]
    end

    S1 --> S2 --> S3

    classDef stage fill:#e2e8f0,stroke:#3b82f6,color:#1e293b,stroke-width:1.5px,font-weight:600
    classDef step fill:#f1f5f9,stroke:#64748b,color:#0f172a,stroke-width:1.5px
    class S1,S2,S3 stage
    class C1,T1,R1 step
    linkStyle default stroke:#64748b,stroke-width:1.5px
```

**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](https://docs.redaction-technique.org/en/toolkit/api-documentation-template/) and explore [About this manual's API](https://docs.redaction-technique.org/en/about-the-api/).

---

## Related toolkit resources

- [Concept article template](https://docs.redaction-technique.org/en/toolkit/concept-article-template/) — Practical Markdown authoring template for conceptual articles.
- [Task article template](https://docs.redaction-technique.org/en/toolkit/task-article-template/) — Practical Markdown authoring template for procedural, step-by-step guides.
- [Reference article template](https://docs.redaction-technique.org/en/toolkit/reference-article-template/) — Practical Markdown authoring template for lookup specifications.
- [API documentation template](https://docs.redaction-technique.org/en/toolkit/api-documentation-template/) — Specialized reference template for REST API endpoints.
- [Example: a well-structured Markdown page](https://docs.redaction-technique.org/en/toolkit/example-markdown-page/) — An annotated worked example of a concept article.
- [Structured and unstructured formats](https://docs.redaction-technique.org/en/formats/structured-vs-unstructured-formats/) — In-depth comparison of DITA XML and unstructured publishing.

---

Source: https://docs.redaction-technique.org/en/toolkit/information-types/