Uwazi Docs: Why our new product documentation works the way it does

The worst page in a product documentation site is not the one that is missing. It is the one that reads well, sounds current, and describes a button that was renamed two releases ago. Nothing on the page warns you that it is outdated. You only find out after the instructions fail.

To address this problem instead of restating it, we have rebuilt the product documentation for Uwazi, our open-source tool for building structured, searchable records. The result is Uwazi Docs. The most interesting part of this rebuild is not the writing process but the standards that live in the repository together with the content, as opposed to being in one person’s head.

Here we explain the main idea behind the rebuild, as well as the three mechanisms that carry it, and what each one of them costs.

The main idea

Uwazi exists so that organisations documenting rights, events, and cases can keep a structured record instead of a folder of loose files. It asks its users for a discipline. To decide what kind of thing each record is. To describe it the same way every time.

Uwazi’s previous product documentation was a folder of loose files. Pages accumulated across years of contributions, each written in the moment, with no style guide and no automated check. Very little connected one page to the next. As Uwazi evolved over time, the pages of its product documentation did not evolve with it, and drifted away from the very software it described.

So the rebuild turned the product’s discipline inward. Writing product documentation is not exactly the same as the work that Uwazi users do, but both will fail the same way when there is no discipline and when each record follows its own rules.

Three mechanisms carry this discipline forward: machine-enforced rules, four types of pages, and AI-human co-writing. Rules enforced by a machine ensure pages describe things in a similar way. Four kinds of pages make each one declare what it is. The third puts both of these to work: AI drafts each page from Uwazi’s source code, following the rules and adhering to the page type. To complete it all, a person checks the draft before it goes live.

Each of these carries a specific cost, and that is the honest part as these are deliberate choices within each mechanism.

Machine-enforced rules

Describing things in the same way starts with writing down what “the same way” means. A style guide came first. But a style guide on its own enforces nothing for long. The person who wrote it gets busy, forgets a rule, or leaves.

So we turned the guide into input for a machine. A prose checker called Vale runs 24 rules against every page, every time someone changes it. The rules do not carry equal weight. Seven block a change from going live, and each of those has one correct answer, like the Oxford comma or alt text on an image. The other 17 only warn. They cover judgement, like readability for non-native English speakers.

A machine can score a sentence. It cannot decide whether that sentence is truly hard to read. So the machine blocks what it can settle and hands the rest to a person. The cost of this is real. A literal rule sometimes blocks a sentence that reads fine, and pages ship with known warnings. That is the price of a check that treats every page alike.

Four kinds of pages

Uwazi asks its users to decide what kind of thing each record is before they describe it. The product documentation now does the same. Nearly every page about the product is one of four kinds: a tutorial, a how-to guide, a reference, or an explanation. The split follows Diátaxis, a widely used framework for technical documentation.

Each kind makes a different promise. A tutorial teaches you something if you follow it through. A how-to guide gets you to a result you already want. A reference page states facts you can rely on. An explanation, like this piece, gives the context and reasons behind how something works.

Mixed into one long guide, those promises blur. A reader has no way to tell whether a sentence is a step, a fact, or a point of view. Knowing the kind of page tells them how to read it before the first sentence. The cost is duplication. One feature can appear in several kinds of pages, so changing one fact can mean editing several files. We pay that cost on purpose.

Rules and page types set the standard for making the product documentation consistent and useful. The last mechanism decides who applies it, and who has the final word.

AI drafts, a person decides

Keeping up with every Uwazi release is too much for one person. So we use AI, inside one fixed line: AI drafts, and a person decides.

A draft starts in Uwazi’s source code, not in someone’s memory of an old release. A renamed button shows up in the code before it shows up on a page. The AI reads how the feature works, and a person checks that reading before any writing starts. The AI then writes the page for its kind and runs it against the rules until nothing blocks it. It also keeps a record of its past mistakes, so the same one is less likely to come back.

Then a person reviews the draft. The code shows what the software does. It says nothing about which parts a reader needs, or where they will get lost. A reply asking for even one fix does not count as approval. Only a person approves a page, and only a person publishes it.

Keeping a person in charge costs speed. The pipeline could run from code to published page without stopping. Instead it stops twice and waits for a person each time. That pause is deliberate. It keeps a person accountable for every page, as our AI policy requires.

What holds the three together

We do not have a dedicated product documentation team. The rebuild was led by one pair of hands, and one person is a single point of failure. No mechanism removes that. None of them revisits old pages either. When Uwazi changes, pages written before the change still need a person to check them.

What the three mechanisms do is move the standards out of one person’s head and into the repository. The style guide and its rules are files, and so are their exceptions. The four kinds of pages show in the structure of the site. The AI follows the same files as everyone else. Someone arriving next year can read all of it, question any of it, and change it.

Uwazi asks the same of its users. Do not keep the structure in your head. Put it in the record, where someone else can find it and trust it.

See also

• Uwazi Docs: Our rebuilt product documentation platform described in this article

• Uwazi Knowledge Hub on GitHub: Our repository with the style guide, the rules, and the content