# How we document

> The rules behind the up4 docs: two areas for two kinds of readers, labels and prices taken from the product, every task walked through in the real app before a release, and an API reference generated from the code.

Source: https://upfour.io/docs/how-we-document

Documentation is only useful if you can rely on it. These are the rules the up4 team follows, and the checks that hold us to them.

## Two areas, two kinds of readers

The [guide](https://upfour.io/docs) is for people who use the app. It starts with a task, such as [watching a website](https://upfour.io/docs/watch-a-website.md), uses the words you see on the screen and ends with what you see when it worked.

The [developer docs](https://upfour.io/docs/api.md) are for people and programs that call the API. They start with the contract: authentication, request and response shapes, errors. The two areas meet only in a folded "Per API" box at the end of a task page.

## Facts come from the product

We don't type what the product already knows:

- **Labels.** Every button, field and menu name on a guide page is read from the app's own texts when the docs are built, in English and in German. If a label in the app changes, the page changes with it. If a label disappears, the docs build fails.
- **Prices.** Cost examples are calculated with the same formula as the estimate in the app, not written by hand.
- **Timings.** Values such as how many results confirm an outage are exported from the code that makes the decision, and a test keeps both equal. The interactive timeline on [When you get alerted](https://upfour.io/docs/how/when-you-get-alerted.md) runs on these values.

Where the product has no fixed number, for example how long an email takes to arrive, we explain what it depends on instead of promising one.

## Every task is walked through

Each task page has a script that does what the page describes, step by step, in a real running copy of up4 with an example company. It uses the labels the page names and takes the screenshots you see, once in English and once in German.

A release checks that these walkthroughs passed for the current guide pages and app texts. If a page or the app changed since the last successful run, the release stops until the walkthroughs pass again. A page cannot quietly describe a screen that no longer exists.

## The API reference comes from the code

- Request and response schemas are generated from the types each route actually uses. A public route without a declared type fails the build.
- Response examples are recorded from test runs against the API and anonymized, not written by hand.
- The [API changelog](https://upfour.io/docs/api/changelog.md) is generated from the difference between two versions of the specification.

## How we write

- Headings name the task. Steps are numbered, with at most seven in a row.
- Short sentences in plain language, no marketing words.
- Every task page says what up4 does not do there. A limit you learn from the docs is better than one you find in production.
- The guide is written in English and German, each by itself, not translated sentence by sentence. The German pages address you with "du" and use no gender forms.
- Pages about moving from another tool compare only what we checked in that tool's current product or public docs.

## For tools and agents

Every page is also available as Markdown: add `.md` to its address, or use "Copy page" at the top. [llms.txt](https://upfour.io/llms.txt) lists the pages for language models, separately for the guide and the developer docs.

## Tell us when a page is wrong

At the end of each page we ask whether it helped. We count yes and no per page, without cookies. With a no you can add one sentence about what was missing, which reaches the up4 team. A page that collects no answers gets rewritten.

## What up4 does not do here

- Pages show no verification date. The walkthroughs protect releases; they are not a public badge.
- Screenshots show example data from the test company, never customer data.
- The developer docs are in English. The quickstart and the basics also exist in German.