Skip to content

Docs

Product documentation

Write a product’s docs next to its tickets, in Markdown, and on Business keep them true with proposals from merged pull requests.

Every product has a Docs tab, on every plan, including Free: a tree of pages written in Markdown, next to the tickets they describe.

Write pages

Open a product and choose Docs. Add a page at the top or under another page, and write in Markdown with a preview beside it. Deleting a page deletes the pages under it.

  • Members who can see the product write pages. Its guests read them.
  • The docs follow the product’s visibility: whoever can’t see a team-only product doesn’t see its pages, in search and over MCP either.
  • Changes to pages are in the audit log on Business, and pages are part of the workspace export.

Search looks through the titles and text of a product’s pages. Each word matches the start of a word, so pay finds “payments”, and the results show the passage with the words marked.

Verified pages

On Business, the docs can follow the code. In the product, turn on Settings → Code → Propose documentation updates after merge; it is off until you do.

  1. When the last open pull request of a ticket is merged, NEWWORK Projects reads the diffs, the ticket and the product’s pages, and proposes edits to existing pages or a new page.
  2. Every change must quote the diff or the ticket. The server checks each quote character by character against the linked pull requests, and each edit must match exactly one place on the page. Changes that fail are left out and listed under Not proposed, needs a person, with the reason. When nothing visible to users changed, the proposal says so.
  3. Documentation update on the ticket shows each change as a diff with its evidence. A project manager or the assignee picks the changes and applies them. Nothing is written before that, and if a page was edited after the proposal was written, applying refuses and asks for a new proposal.

Applying marks each page it wrote with the pull request it was checked against, such as Verified · acme/payments #42. When someone changes the text by hand afterwards, the page says Edited since verified until the next applied proposal checks it again.

A proposal only changes pages of its ticket’s product. Pull requests are linked by the GitHub, GitLab or Bitbucket connection (see Getting started) or by an agent with pm-pr-link. Writing a proposal counts as one AI action, unless the workspace uses its own OpenAI key.

Agents and the docs

  • pm-docs-search lists a product’s pages, or searches them; pm-doc-get reads one page as Markdown, with the pull request it was last verified against and whether it was edited since. Both work on every plan.
  • On Business, an agent that built a ticket can propose the change itself with pm-doc-proposal-submit. The same checks apply, and a person still applies it. pm-doc-proposal-get, pm-doc-proposal-request and pm-doc-proposal-apply read, queue and apply proposals.

After a downgrade

Pages stay, and stay writable. Proposals can no longer be requested or applied, and the setting can only be turned off.