Living documentation

Every project accumulates knowledge that lives nowhere: how a feature actually behaves, why a thing was built the way it was, what an admin has to do to switch it on. It stays in your head, and every time somebody asks, you explain it again.

Docs is where that goes. Each project has its own library, on the Docs page in the project sidebar.

What a document is, and what it isn't

Waymarq already holds two kinds of writing, and this is a third:

Files are what was asked for — a brief, a contract, a spec somebody sent you. They're uploaded and never edited in place.
A task's specification describes one piece of work, and stops being interesting once that work is done.
A document describes how the finished thing behaves. It outlives the tasks that produced it, and it's meant to be edited.

If you find yourself explaining something for the second time, that's a document.

What deserves a document

Documents describe features, not tasks. This is the one thing worth getting right, and it's the easy mistake: a document per task leaves you with a library full of entries called "Add rate limiting middleware" — accurate, and useless, because nobody would ever go looking for that.

A feature is something you'd name out loud. "Signing in with a one-time code." "The client share link." "How invoicing works." It maps onto the work however it happens to have been built:

A whole phase, when that phase is one coherent thing.
A few tasks inside a phase, when the phase holds three unrelated pieces of work.
Tasks spread across phases, when a capability got built in stages.
One task, when it genuinely stands alone.
Everything, for a "how this all fits together" overview.

What you link is also the level. There's no separate depth setting — link one task and you've written about one thing; link every phase and you've written an overview.

Three questions that usually settle it:

Would someone ask "how does X work?" using those words? If not, it's part of a bigger feature.
Can you write three useful paragraphs that aren't just the task description reworded? If not, extend an existing document instead.
Is it internal plumbing — a refactor, a config change, a bug fix? Then no. That changes how the thing is built, not how it behaves.

When in doubt, add to an existing document rather than starting a new one. One document about sign-in that also covers SMS codes beats two, one of which nobody will find.

Who it's written for

Every document is marked as one of three, which changes how AI writes it and tells a reader what to expect:

User guide — for whoever uses the thing. What it does, how to do it, in the words that appear on screen. No implementation detail.
Technical — for whoever maintains it. How the pieces fit, what decisions were made and why.
Reference — a lookup rather than a narrative. Tables, options, values.

A project can hold all three. Under Project settings → General you can set which one AI reaches for by default, so a project where you only ever want technical notes doesn't keep producing user guides.

Writing one

By hand. New document, give it a title, and write in markdown. This works with AI switched off entirely — it's a place to put what you know.

With AI. Write with AI, pick the phases it should cover, and Waymarq reads the tasks inside them and writes up how the finished work behaves. You can add a line about what to focus on ("cover how an admin configures it"). Edit it afterwards like anything else.

AI writes only from the work you point it at. If something isn't covered by those tasks, it's left out rather than invented — a short accurate document is worth more than a complete-looking made-up one.

Keeping it true

Link a document to the phases and tasks it describes, and Waymarq watches them. When that work changes, the document says so at the top: the work behind this has changed.

It is a flag, not an action. Nothing rewrites itself, ever — a document you spent an afternoon editing being quietly replaced overnight is exactly the thing that stops people trusting their own documentation. When you want it brought up to date, Bring it up to date rewrites it from the current work, and editing it yourself clears the flag too.

Nothing is ever lost

Every version a document has had is kept, under History — who wrote it, when, and whether it came from a person, from Waymarq's AI, or over the API. Any of them can be restored in one click, and restoring is itself recorded, so putting back the wrong one is just as recoverable.

That's what makes it safe to let something else write your documentation.

Letting a coding agent maintain them

If you use an AI coding assistant, it can read and update these documents directly through the REST API — so the agent that just changed how something works is the one that updates the description of it.

Two calls do most of the work:

GET /api/v1/tasks/{task}/documents — given a task it's about to pick up, what already documents that area. So it extends the right document instead of starting a near-duplicate.
GET /api/v1/projects/{project}/documents/coverage — what nothing describes yet, so it can see where the gaps are and judge which of them add up to a feature worth writing about.

You don't need to explain any of this. The prompt on Organisation settings → API → Import guide already includes it, and tells the assistant to document features rather than tasks, to check before starting and update when finishing. Paste that in and the thing you keep asking about writes itself down.

Every write from an agent lands as a revision, the same as any other, so you can see exactly what it changed and put it back if you disagree.

Turning it off

Docs is a per-project feature, under Project settings → Features. A project that doesn't need it loses the nav item entirely.