The Diataxis Framework¶

Conflux documentation is structured around Diataxis, a framework for technical documentation that organises content by the reader's need rather than the subject matter.

Why Conflux uses Diataxis¶

Conflux is a growing integration platform. Its documentation serves readers with very different goals at the same time: a new developer who has never worked with integrations needs something completely different from an experienced engineer troubleshooting a webhook handler, and both differ from an ops engineer who needs to know which queue a job lands on. Without a deliberate structure, documentation tends to blur these needs together — tutorials drift into reference material, how-to guides accumulate background explanations, and readers end up hunting through the wrong type of content for what they actually need.

Diataxis solves this by making the reader's need the primary organising principle. Each page serves exactly one need. Once a reader knows the system, they can navigate directly to the right type without wading through material that does not apply to them.

The four domains¶

Diataxis defines four types of documentation, each answering a different question.

Tutorials answer: "How do I get started?" They are learning-oriented. The reader is a newcomer who wants to build confidence by completing something real. A tutorial leads the reader through a working sequence of steps — the goal is not the thing they build, but the understanding they gain along the way.

How-to guides answer: "How do I accomplish this specific task?" They are task-oriented. The reader already understands the domain and wants to reach a concrete outcome. A how-to guide assumes competence and gets out of the way — no background, no teaching, just the steps needed to do the thing.

Reference answers: "What exactly does this do?" It is information-oriented. The reader is working and needs accurate, structured facts about the system — a configuration key, an event payload, a method signature. Reference material mirrors the code and stays in sync with it as things change. For API endpoints, Scribe generates this automatically from controller docblocks.

Explanation answers: "Why does it work this way?" It is understanding-oriented. The reader wants to think, not act. Explanation discusses the reasoning behind design decisions, the trade-offs that were considered, and the broader context that makes a concept make sense. This page is an example of that.

The reader's need determines the type¶

The same subject can — and often should — appear in all four types as separate pages. The integration data flow, for example, might be introduced in a tutorial, described step-by-step in a how-to guide for adding a new integration, catalogued precisely in a reference page, and examined conceptually in an explanation. None of these duplicates the others because each serves a different reader in a different situation.

When deciding which type a page belongs to, the question is not "what is this page about?" but "what does the reader need right now?" A reader following a tutorial needs to complete something and gain confidence. A reader consulting reference material needs accuracy and completeness. Mixing these needs on the same page forces every reader to work harder to find what they came for.