Documentation-Driven Adaptive UX

The Documentation / Interface Disconnect

Enterprise software usually treats product knowledge and product behavior as separate systems. The application knows its state. Validation knows which values are required. Documentation explains concepts, release notes describe version changes, and implementation guides tell users how to make a choice. Those sources often live outside the interface that needs them.

One possible detour is familiar in shape: a user reaches a configuration field, encounters uncertainty, leaves the application to consult documentation, interprets what they find, and returns to the task. This is the design problem illustrated below, not a measured journey in this experiment.

Move the knowledge, not the user.

Conceptual comparison · not a measured outcome

Two paths through the same task

01

Conventional

External detour

The task crosses the product boundary before it can continue.

1. Work in product

   Active task

2. Hit a blocker

   Meaning is unclear

3. Leave productOutside app

   Context breaks

4. Search documentsOutside app

   Find and interpret

5. Return to product

   Resume the task

02

Adaptive

In-product path

The task stays in place while applicable knowledge reaches the interface.

User stays in the product — authored guidance meets them at the field.

Decision one

Applicability

Does this fragment apply to the current version, user, and field state?

Decision two

Response policy

If it applies, what may the interface do — explain, guide, or offer?

Two decisions · kept separate

Guidance may explain or guide. An offer appears only when exactly one valid option exists — and the user still accepts it. The note cannot choose a value.

The opportunity is not simply to move documentation into a tooltip. A static tooltip gives every user the same explanation. Here, explicit conditions select a note for the current version, simulated familiarity, and field state; separate application rules determine whether the interface may explain, guide, or offer a value. This does not determine what an individual user actually needs.

The reference experiment makes this concrete at one required Data Connection field. A standard form and an adaptive form receive the same version, simulated user familiarity, compatible options, and validation rule. The adaptive form can explain a missing choice, vary authored guidance, or offer the sole compatible connection for the user to accept; it cannot choose among several. The working comparison is linked below, after the decision boundaries that explain it, and lives with the companion project.

Start with Application Truth

The first architectural rule is simple: the application remains authoritative. Documentation can explain a rule, but it should not redefine it. Product knowledge can enrich the experience, but deterministic business logic should remain deterministic.

Taking that rule seriously separates the experiment into seven concerns. They fall into three groups, and the groups are also the order in which a decision is made: the application establishes what is true, authored knowledge is selected against that truth, and only then does the interface decide how strongly to respond and how to show it. The later groups depend on application truth, but they do not redefine it. Phase 1 makes these decisions without inference.

Figure 01

Seven concerns, decided in one direction

Research · deterministic Phase 1

Application truth

Authoritative

Domain state

What the user has selected.

Runtime and user context

Product version, familiarity, and compatible options.

Validation

Deterministic application requirements.

Applicable knowledge

Reads truth

Product knowledge

Authored explanation and configuration guidance.

Knowledge applicability

Whether a specific item applies to the current state.

Structured response

Bounded by evidence

Response policy

How strongly the interface may intervene.

Rendering

How the structured response appears.

Keeping these responsibilities visible gives later AI capabilities a clean place to enter without asking them to replace validation, compatibility rules, or product state.

Why Deterministic First?

A required field, a version-specific note, or a single compatible option is already knowable from application state and authored rules. Starting there lets Phase 1 test the separation between product truth, relevant guidance, and permission to intervene without introducing inference as another source of uncertainty.

Structured Product Knowledge

The reference implementation does not ingest real documentation yet. Instead, it models small authored knowledge fragments that approximate what a future ingestion or authoring pipeline could produce.

The fragments include a basic Data Connection summary, required-field help, a beginner-oriented concept explanation, version 4.2 guidance, and configuration-selection guidance. Each carries applicability information such as audience, version, and state conditions, plus provenance identifying whether it represents documentation or a release note.

Version-specific knowledge applies only when the product is at least version 4.2 and the Data Connection is missing. Beginner help applies only to a new user in the same missing-connection state.

Context selection, not context accumulation.

The goal is not to dump all related documentation into the interface. First narrow the available knowledge according to deterministic facts, then decide how much of it deserves to become interface behavior.

Knowledge Applicability Is Not Response Policy

Knowing something applies does not automatically determine what the interface should do with it.

Knowledge applicability asks whether authored information matches the current product state, version, and audience. Response policy asks how strongly the interface should intervene given that state, the validation result, available knowledge, and certainty of the evidence.

A version note can be relevant without deserving a modal. A beginner explanation can apply without changing validation. A configuration guide can apply while the interface still refuses to choose among several valid options.

This separation becomes especially important if semantic retrieval is added later. Retrieval can rank or discover relevant knowledge while response policy still decides whether the result becomes help text, a highlight, a suggestion, or an action.

Figure 02

A fragment may apply without earning an action

Research · applicability / policy

Decision A · matching knowledge

Required-field helpMissing selection · Explains the existing requirement

Beginner conceptNew + missing selection · Does not appear for experienced users

4.2 release note4.2 + missing selection · Changes explanation, not validity

Selection guidanceMissing selection · Cannot determine which system the user intends

Decision B · permitted response

Validation asks whether the selected value meets the application requirement.

Policy considers that result, the compatible options, applicable guidance, and certainty before deciding to explain, guide, or offer.

A matched release note can add context. It cannot select a Data Connection or change a validity rule.

UI Authority Should Follow Evidence

Stronger intervention needs a narrower, explicitly authorized basis; certainty about compatible options is not certainty about the user’s intent. A response policy might range from no intervention through explanation, help, highlighting, and guidance to an offer to use the sole compatible value. In Phase 1, accepting that offer is the user’s action; the interface does not silently set the field or perform an autonomous destructive action.

The critical boundary is between guidance and choice.

If several Data Connections are compatible, the system can explain the requirement and guide the user toward the field, but it does not know which connection matches the user’s intent. It must not guess.

If exactly one compatible Data Connection exists in the controlled scenario, the interface may offer it as an explicit user-accepted action. The candidate count removes ambiguity among the available values; it does not establish the user’s intent or guarantee that the connection is appropriate for their task.

Scenario Evidence

The experiment makes differences between controlled states inspectable; no single message establishes an outcome. Both surfaces start from the same scenario and application truth while maintaining independent interaction state for comparison. Figure 03 records what each state permits—and where the response stops.

Figure 03

Five scenarios, five response boundaries

Bridge · observed lab scenarios

ScenarioEvidencePermitted responseBoundary

1. 01Several compatible

   Multiple valid values; intent unknown

   Explain, highlight or focus, guide

   No guessed selection

2. 02Exactly one

   Only one compatible value

   Offer “Use connection”

   User must accept; no silent mutation

3. 03New / experienced

   Familiarity is a demo control

   Include / omit beginner explanation

   Same validation

4. 04Version 4.1 / 4.2

   Version is a demo control

   Include 4.2 note only in 4.2

   Same validity rule

5. 05Valid selection

   Required field satisfied

   Remove missing-field intervention

   Do not keep prompting

What Phase 1 Actually Shows

These are properties demonstrated by the deterministic reference implementation, not measured improvements in comprehension, task success, or safety.

A future AI layer has a narrower job than “control the UI.”

The deterministic experiment suggests that inference should resolve ambiguity rather than invent application truth. That is a much smaller and safer responsibility than asking a model to infer the entire interaction model at once.

Limitations of the Current Experiment

Phase 1 is not a production adaptive-UX platform. Its product knowledge is authored fixture data, its compatibility scenarios are fixed demo data, and user familiarity is a simulation control rather than an inferred or persisted profile.

The experiment also does not answer how knowledge fragments are reviewed, stale release guidance is retired, conflicting sources are reconciled, or intervention quality is measured. Those are not omissions hidden behind the demo; they are deliberately outside the Phase 1 question.

Where AI Could Enter Later

The deterministic architecture gives future inference explicit seams. Optional inference could sit after deterministic filtering and before evidence reconciliation and response policy.

Where such inference would run is a separate, unevaluated question. Browser-local processing could keep some application context on the device; routing between browser, local service, and remote model would be a deployment decision, not another interface capability.

Figure 04

Inference has a place, not a mandate

Research · future only

1. 01 · Implemented

   State + validation → explicit context filtering → applicable authored fragments

2. 02 · Optional, proposed

   Intent mapping, candidate ranking, or explanation adaptation

3. 03 · Authority boundary

   Evidence reconciliation → response policy → structured UI response

Browser / machine-local / server / edge / cloud: later placement question, not active runtime routing

Inference should resolve ambiguity, not replace truth.

From Documentation Portal to Product Capability

The broader direction is not to eliminate documentation. Long-form documentation remains necessary for learning, implementation, troubleshooting, and reference. The opportunity is to stop treating it as useful only after the user leaves the product to search for it.

Some product knowledge can be structured with its concept, applicability conditions, audience, version, and provenance. Application state and response policy—not the knowledge fragment alone—determine whether and how the interface may act on it.

At that point, documentation is no longer only a destination. It becomes one input into interface behavior. The strongest version is not an interface that constantly talks: it becomes quieter when context is obvious, more explanatory when uncertainty is predictable, and more helpful only when the available evidence justifies it.

How adaptive can an enterprise interface become before AI is necessary?

In this reference implementation, far enough to tailor guidance and offer an unambiguous choice without inference. Whether that improves the experience—and where inference would add value—remains to be tested.