A team writing workflow that works

Three people writing in the same docs site is fine. Eight is fine. The problem is never the team size — it's the absence of a workflow. Here's the one we've seen work consistently across ~500 Docsio teams.

Roles map to people, not titles

Every project has one Owner and any number of Editors. (Pro plans also have Viewers, but those are read-only.) The Owner pays for the project and can delete it; Editors can do everything else.

That's the whole role system. Don't overthink it. Simple permissions hold up better than complicated ones.

The three workflows we see

1. Single-author with periodic reviews

One person writes. A second person reviews drafts before publish. Most appropriate for: small companies with a single technical writer or marketing-team-of-one.

How to make it work in Docsio:

The author edits in Docsio's editor live.
Before publishing, they tag a version (Pro) so there's a snapshot.
They publish to a password-protected URL or share the live URL with the reviewer.
Reviewer comments via Slack, Linear, or a doc — Docsio doesn't do in-line review yet.
Author applies feedback, publishes again.

2. Engineering writes, writer polishes

Engineers commit drafts via GitHub Sync. A writer rewrites for clarity in Docsio's editor. Most appropriate for: SaaS with a technical writer and a few engineers contributing reference content.

How to make it work:

GitHub Sync set to bidirectional. Engineers edit in their IDE, push to the configured branch.
Pushes auto-publish; writer sees the new content live.
Writer edits in Docsio's editor, AI agent helps rewrite.
On publish, Docsio commits back to GitHub. Engineers see the polish on their next pull.
Friction is on first runs — editors and writers learn the rhythm.

3. Per-section ownership

Different teams own different sections of the docs. Most appropriate for: large products with distinct surfaces (API, dashboard, integrations).

How to make it work:

Each team has 1–2 Editors on the project.
Convention: each section's pages are only edited by that team's Editors.
Use git history (via GitHub Sync) to see who's been touching which pages.
Quarterly audit: walk the sidebar, ask each team if their section is current. Promote stale-but-important pages to a refresh sprint.

What about real branching / PR review?

Docsio doesn't have a built-in PR workflow yet (it's on the roadmap). Today the closest workflow:

Use GitHub Sync, with a non-default branch as the configured sync branch.
Authors work on that branch; another team reviews via PR in GitHub.
Merge to main → main pushes → Docsio rebuilds.

Heavy for most teams. Worth it for compliance-driven docs (legal, security, healthcare).

Things that break

Two people editing the same page in the editor at the same time. Docsio doesn't lock — last write wins, and you'll see a "draft saved" toast for the older edit. Use the version-history tab to recover. Communicate before deep edits.
Bulk renames without redirects. Rename a slug, and any inbound link breaks. Be deliberate about URL changes; if the old URL is widely linked, keep the slug and rename the title instead.
Editors who never publish. If your draft sits unpublished for two weeks, someone else editing the same page will overwrite without seeing your changes. Publish small, publish often.

Start with workflow #1. It's overkill for ~80% of teams to do anything more.
Move to #2 when you have engineering contributors filing PRs to your repo.
Move to #3 only when team size or section count makes #2 unworkable.

The point of a workflow is to prevent collisions, not to feel professional.