Documentation structure

Documentation structure#

This page explains why the TUI Forms documentation is organised the way it is, and how to navigate it depending on what you need.

The framework: Diátaxis#

The TUI Forms documentation follows the Diátaxis framework, which organises documentation into four distinct types based on what the reader needs to do:

Type	Oriented towards	Answers the question
Tutorials	Learning	"Can you teach me?"
How-to guides	Specific goals	"How do I...?"
Reference	Information lookup	"What does X do?"
Concepts	Understanding	"Why does it work this way?"

Each type serves a different reader in a different situation. Mixing them—for example, writing explanations inside a reference page—makes documentation harder to use. Diátaxis keeps them separate so you can find what you need without reading everything.

Why Diátaxis?#

Documentation that grows organically tends to blur these boundaries. A "guide" might start with a tutorial, drift into explanation, and end with an API reference—useful to the author who wrote it, but disorienting to the reader who arrives mid-task.

By committing to Diátaxis from the start, TUI Forms documentation stays navigable as it grows. Each page has a single purpose, and the section it lives in tells you what to expect before you read a word.

What each section contains#

Tutorials#

Not yet written.

Tutorials walk a complete beginner through a self-contained learning experience. The goal is understanding, not production use—a tutorial may simplify or omit details to keep the reader moving.

How-to guides#

Practical, task-oriented instructions for readers who already know the basics and need to accomplish a specific goal. Each guide starts from a concrete problem and ends when the problem is solved.

Current guides:

Use in your project: install TUI Forms and render your first form
Create a custom renderer: implement a custom renderer backend
Contribute to TUI Forms: set up a development environment and submit changes

Reference#

Technical descriptions of every supported construct, class, and method. Reference pages describe the machinery; they do not explain the reasoning behind it or walk you through using it.

Current reference pages:

JSONSchema support: which JSONSchema constructs TUI Forms recognises
BaseRenderer: the BaseRenderer abstract class and its methods
stdlib renderer: how the stdlib renderer presents each question type
rich renderer: how the rich renderer presents each question type
cookiecutter renderer: how the cookiecutter renderer presents each question type

Concepts#

Understanding-oriented pages that explain why TUI Forms works the way it does. Reading a concepts page will not tell you how to accomplish a task, but it will give you the mental model to work effectively with the library.

Current concepts pages:

Schema-first design: why TUI Forms uses JSONSchema as its form definition language
Documentation structure: this page

How to navigate#

If you are new to TUI Forms and want to get something working quickly, start with Use in your project.

If you have a specific question such as "how do I add a conditional field?," go to the Reference section and check JSONSchema support.

If something is not behaving as you expect and you want to understand the underlying model, read Schema-first design.

If you want to extend TUI Forms with a custom renderer, follow Create a custom renderer and use BaseRenderer as a look-up resource while you write the code.