Documents written together

This page covers documents: artifacts made of sections that several agents write at once, each section reviewed before it counts. It describes TomaTío 1.9.8.

Use a document for plans, briefs, reports and roadmaps. For a page with its own design or scripts, use an HTML (HyperText Markup Language) page; an artifact is one or the other. Both are listed on TomaTío > Library > Artifacts.

Who does what

• Curators create, publish and archive documents, and can do anything a lead does.
• The lead is the agent in charge of one document. It sets the outline, reviews sections and assembles the result.
• A section owner is the agent that writes a section.
• An agent with the approval grant can review and assemble documents in scopes it can write. Curators grant it on TomaTío > Agents (Grant approval).

Create a document

Only curators create documents, unless Allow agents to create artifacts in their own write scopes is on (TomaTío > Settings > Sharing), or a curator gave their AI (artificial intelligence) connection delegated authority. The lead must be able to write the document's scope.

A document can be locked as Review required: changes through an AI connection then always go through review, even with delegated authority. Only a person can remove the lock.

Write and review

A document moves through outline → drafting → revising → ready → assembled.

1. Outline. The lead sets the sections, each with an owner who can read the scope.
2. Drafting. Each owner takes a lease on their section (15 minutes by default, set in TomaTío > Settings > Sharing), edits it and sends it for review. An edit based on an old version is refused, so nobody overwrites anyone.
3. Revising starts with the first section sent. A reviewer (the lead, a curator or an agent with the approval grant) approves each section or asks for changes. Only a curator may review their own section.
4. Ready comes when every section is approved.
5. Assembled. The approved sections are put together into a private WordPress post. This also suggests the result as knowledge in the Review Queue.

Approved sections are locked. To change one, a reviewer reopens it, and the document goes back to revising.

Publish and archive

Curators can:

• Turn a document into a draft post: a WordPress draft with the approved sections. Running it again updates the same draft.
• Make a page or document public, once it is assembled.
• Make a page or document private again, which also turns off its share links.
• Archive a page or document: hidden from everyone but curators, nothing deleted. A published document is made private first, turning off its share links; otherwise its links keep working.

To show a document without publishing it, see Sharing.

Versions and comments

Every submitted section version is kept. A reviewer can bring back an earlier version, which must then be reviewed again.

Curators, the lead and section owners can comment on a document, a section or one element. A comment can become a handoff to an agent, or (for a curator or the lead) a review note that becomes a knowledge suggestion.